Erros comuns de análise de JSON e como corrigi-los

Por que JSON.parse lança exceção em vez de adivinhar

Literais de objeto JavaScript são tolerantes: chaves sem aspas, vírgulas finais, strings com aspas simples e comentários são legais, porque o motor analisa esse código como qualquer outro. JSON é uma gramática muito menor e mais rigorosa (RFC 8259), e JSON.parse() impõe cada uma de suas regras sem fallback. O parser lê da esquerda para a direita e para no primeiro token que não se encaixa na gramática naquela posição.

Os criadores escolheram isso de propósito. Um parser JSON tolerante aceitaria documentos ligeiramente diferentes em cada implementação, justamente o problema de interoperabilidade que o JSON queria evitar. O custo: as mensagens de erro são curtas e só indicam posição. O parser diz onde a gramática quebrou, não o que você quis escrever.

Vírgulas finais

O erro de JSON mais comum de todos é uma vírgula final esquecida ao editar um literal de objeto JavaScript (onde ela é legal) sem lembrar que não é legal em JSON.

{
  "name": "Alice",
  "roles": ["admin", "editor"],
}

O V8 rejeita isso na chave de fechamento, e não na vírgula, porque a vírgula em si é gramática válida até o momento em que o parser espera outra propriedade e encontra `}` no lugar. Dependendo da sua versão do Node/Chrome, você verá algo como `Unexpected token '}', "...editor"],\n}"... is not valid JSON` (V8 mais recente, com um trecho) ou o antigo e mais telegráfico `Unexpected token } in JSON at position 47`. De qualquer forma, a correção é a mesma: apague a vírgula antes do colchete ou chave de fechamento.

Aspas simples e chaves sem aspas

O JSON exige aspas duplas para toda string e toda chave, sem exceções. Strings com aspas simples e chaves sem aspas aparecem o tempo todo quando alguém digita JSON à mão ou copia de código JavaScript.

{ 'name': 'Alice' }
{ name: "Alice" }

Uma aspa simples no início produz algo como `Unexpected token ''', "{ 'name'"... is not valid JSON`. Uma chave sem aspas gera outra mensagem: o V8 moderno sabe que esperava um nome de propriedade e reporta `Expected property name or '}' in JSON at position 2` sem citar o identificador isolado. Nos dois casos a correção é mecânica: envolva toda chave e todo valor de string em aspas duplas.

Quebras de linha e caracteres de controle sem escape dentro de strings

O JSON proíbe quebra de linha, tabulação ou outro caractere de controle (qualquer coisa abaixo de U+0020) dentro de uma string. Escape-o como `\n`, `\t` e assim por diante. O problema aparece mais quando o código monta JSON concatenando um valor de várias linhas (uma mensagem de log, um trecho de código, um comentário de usuário) num literal de string sem escapá-lo.

{
  "message": "line one
line two"
}

Isso produz `SyntaxError: Bad control character in string literal in JSON at position 21`, um dos poucos erros de JSON que nomeia o problema em vez de só um token. Escape o caractere em vez de deixá-lo cru: `"line one\nline two"`.

Chaves duplicadas, NaN/Infinity/undefined e caracteres BOM

Três modos de falha mais silenciosos merecem nome. Primeiro, chaves duplicadas num objeto JSON não geram erro de análise. `{ "id": 1, "id": 2 }` é analisado sem problema, e JSON.parse mantém a última ocorrência (`id: 2`) e descarta a primeira sem aviso. A RFC 8259 diz que os nomes 'deveriam' ser únicos, mas não exige que os parsers rejeitem duplicatas, então seu parser segue a especificação, e quem revisa o código deixa esse bug passar com facilidade.

Segundo, `NaN`, `Infinity` e `undefined` são JavaScript válido, mas não são tokens JSON. O JSON tem `number` sem os valores especiais do IEEE-754, e não tem `undefined` (só `null`). `{ "value": NaN }` lança `Unexpected token 'N', ..."value":NaN}"... is not valid JSON` (ou `Unexpected token N in JSON at position 10` em motores mais antigos). `JSON.stringify` converte `NaN`/`Infinity` para `null` e descarta valores `undefined`, então esse erro costuma significar que alguém escreveu o JSON à mão ou que uma fonte não-JS assumiu semântica de JS.

Terceiro, um byte-order-mark UTF-8 (U+FEFF) no início de um arquivo quebra o `JSON.parse` quando você lê o arquivo como string crua, e produz `Unexpected token '\ufeff'... is not valid JSON` na posição 0. Editores do Windows e algumas ferramentas Java/.NET o adicionam ao salvar UTF-8. O problema é do `JSON.parse` sobre uma string: o `Response.json()` da Fetch API decodifica texto UTF-8 e remove um BOM inicial durante a decodificação, então os mesmos bytes podem se comportar de forma diferente via HTTP e lidos do disco com `fs.readFileSync(path, 'utf8')`.

Lendo a posição, e quando usar uma ferramenta de reparo

A `position` num erro de JSON.parse é um deslocamento de caracteres indexado a partir de zero na string que você passou, não um número de linha. O Node (v20+) também anexa um `(line X column Y)`, mas runtimes e navegadores mais antigos dão só o deslocamento cru. Duas coisas confundem as pessoas. A posição marca onde o parser notou a gramática quebrada, e para uma vírgula final ou um colchete faltando ela costuma ficar um token depois do seu erro. E se você formatou o JSON para ler enquanto depura a string minificada original, os deslocamentos não vão bater com o que aparece na tela.

Para um deslize de sintaxe pontual num documento curto, corrija à mão depois de achar a posição. Cole o documento num validador que destaque o caractere em vez de contar deslocamentos. Para um arquivo grande com vários erros não relacionados, JSON saído de uma ferramenta upstream com bugs, ou JSON estragado por várias rodadas de copiar e colar, a correção manual toma tempo demais. Aí vale automatizar. O JSON Validator do JSONForge aponta cada violação de schema com um caminho preciso assim que o documento é analisável, e o JSON Repair corrige erros estruturais comuns (aspas faltando, vírgulas finais, colchetes desbalanceados) quando a entrada está danificada demais para corrigir um erro de cada vez.