Como corrigir JSON inválido: os 7 erros que quebram todos os analisadores

A análise JSON parece trivial até que um único caractere perdido interrompa sua construção cinco minutos antes da implantação. JSON é intencionalmente rígido, mais rígido que JavaScript, e é exatamente por isso que os desenvolvedores vindos de JS continuam sendo pegos de surpresa. A boa notícia é que quase todo erro de “JSON inválido” é um dos sete erros comuns. Aprenda a reconhecê-los e a maioria dos JSON corrompidos está a um caractere de ser válido.

1. Vírgulas finais (o culpado número um)

Este é o erro JSON mais comum. JavaScript permite deixar uma vírgula após o último item de um objeto ou array; JSON, de acordo com sua especificação RFC 8259, não. Portanto, {"name": "Alice", "age": 30,} é inválido por causa daquela vírgula depois de 30, e ["a", "b",] é inválido pelo mesmo motivo. A correção é simplesmente remover a vírgula após a propriedade final ou elemento da matriz. Este morde a todos, desde os juniores editando manualmente um arquivo de configuração até os idosos colando um trecho de JavaScript.

2. Aspas simples em vez de aspas duplas

JSON requer aspas duplas em torno de chaves e valores de string. Aspas simples são válidas em JavaScript e Python, mas não em JSON. Então {'name': 'Alice'} é inválido; deve ser {"nome": "Alice"}. Isso geralmente acontece quando sua carga vem de um console.log JavaScript ou da saída str() do Python. Localizar e substituir aspas simples por duplas geralmente funciona, mas cuidado com apóstrofos dentro de strings, "it's" quebraria, portanto, uma correção com reconhecimento de analisador é mais segura.

3. Chaves não citadas

Em JavaScript você pode escrever chaves de objetos sem aspas: {name: "Alice"}. JSON não permite isso, cada chave deve ser uma string entre aspas duplas. Então {name: "Alice"} deve se tornar {"name": "Alice"}. Este é outro sintoma de copiar um literal de objeto JavaScript diretamente em um contexto JSON.

4. Colchetes ausentes ou incompatíveis

Cada chave de abertura precisa de uma chave de fechamento, e cada colchete de abertura precisa de seu par. Quando eles não correspondem, você obtém o temido “Fim inesperado da entrada JSON”. Eles são difíceis de detectar a olho nu em um arquivo grande, que é onde um formatador que imprime lindamente e destaca a correspondência de colchetes ganha seu sustento, colchetes incompatíveis saltam para fora no momento em que a estrutura é recuada.

5. Comentários

JSON não tem comentários. Não // comentários de linha, nem comentários de bloco. Se você adicionou um comentário para explicar um campo, o analisador rejeitará o arquivo inteiro. As configurações do VS Code usam uma variante chamada JSONC que permite comentários, e há um superconjunto chamado JSON5 que permite comentários, aspas simples e vírgulas finais, mas analisadores padrão como JSON.parse, módulo json do Python e a maioria das bibliotecas de servidor aceitam apenas JSON estrito. Para arquivos de configuração que precisam de comentários, YAML ou JSONC são escolhas melhores do que dobrar JSON.

6. Valores JavaScript que não são JSON válidos

Existem três valores em JavaScript, mas não em JSON: indefinido, NaN e Infinity. Se sua fonte de dados produziu um destes, comum ao serializar objetos que contêm uma conversão numérica com falha, o resultado será JSON inválido. A solução é substituí-los por null (o equivalente JSON de "sem valor") ou um padrão sensato. O bug geralmente ocorre no upstream, no ponto onde os dados foram gerados, e não no próprio JSON.

7. Caracteres sem escape em strings

Certos caracteres devem ter uma barra invertida dentro de uma string JSON. Uma nova linha bruta, uma tabulação ou uma barra invertida literal causará uma falha de análise. Portanto, um caminho do Windows como "C:\Users\Alice" é inválido, as barras invertidas devem ser duplicadas para "C:\\Users\\Alice" e uma quebra de linha real dentro de uma string deve ser escrita como \n. Eles são invisíveis em muitos editores, o que os torna frustrantes para encontrá-los.

O fluxo de trabalho de depuração mais rápido

A pior mensagem de erro JSON é apenas “json inválido” sem localização. Um bom validador faz três coisas: diz o que está errado, diz onde (linha e coluna) e mostra o contexto ao redor. O fluxo de trabalho mais rápido é colar o arquivo em um validador, ler a linha para a qual ele aponta e, em seguida, verificar a linha acima dele, porque o analisador geralmente só percebe que algo está errado quando atinge o próximo token, portanto, uma vírgula ausente na linha 4 aparece como um erro na linha 5. Se o erro apontar para a posição 0, verifique se há uma marca de ordem de byte ou texto perdido antes do colchete de abertura.

Evitando JSON inválido

Três hábitos evitam a maior parte da dor do JSON. Nunca edite manualmente arquivos JSON grandes sem uma ferramenta que respeite a gramática. Impressão bonita ao salvar, porque os erros estruturais são óbvios no JSON recuado e ocultos em uma única linha compacta. E valide antes de confirmar, uma simples verificação em seu pipeline de CI detecta erros de sintaxe antes que eles cheguem a qualquer ambiente. A maioria dos JSON quebrados está a um caractere de válido; o truque é capturar esse personagem cedo.