Resumo: JSON tem uma gramática pequena e rígida — os erros que quebram um parser (vírgulas finais, chaves sem aspas, aspas simples) são invisíveis em dados minificados mas óbvios uma vez formatados. Conhecer as regras reais de sintaxe transforma "a API retornou um erro" em uma correção de dois segundos. Combine este guia com Encoding Converter, Character Counter, Text Difference e AI Hidden Characters.
Formatar JSON significa adicionar espaços e recuo para tornar sua estrutura legível; validá-lo significa verificar se essa estrutura realmente segue a gramática definida na RFC 8259. O JSON minificado — a forma compacta sem espaços que as APIs realmente transmitem — está correto mas ilegível; um formatador reverte isso sem alterar os dados.
As regras de sintaxe que realmente importam
Chaves JSON devem ser strings entre aspas duplas — {name: "valor"} não é válido, apenas {"name": "valor"} é analisado corretamente. Aspas simples nunca são válidas para strings ou chaves, diferente dos literais de objeto JavaScript, que a sintaxe do JSON restringe deliberadamente. Uma vírgula final após o último item em um array ou objeto — ["a", "b",] — é JSON inválido, mesmo sendo inofensiva (ou até exigida por convenção) em outras linguagens, e é uma das razões mais comuns pelas quais JSON editado manualmente falha ao ser analisado.
Por que "parece certo" não é o mesmo que válido
Um documento JSON pode ser visualmente indistinguível de um válido e mesmo assim falhar ao ser analisado — uma chave de fechamento faltando no final de uma grande estrutura aninhada, uma aspa tipográfica (“) colada de um processador de texto em vez de uma reta ", ou um comentário perdido (JSON não tem sintaxe de comentário nenhuma, diferente do JSON5 ou JSONC) vão todos quebrar um parser rigoroso enquanto parecem corretos à primeira vista. É exatamente por isso que formatar antes de olhar ajuda: recuo correto torna uma chave não fechada visualmente óbvia, quebrando o padrão de aninhamento esperado.
Formatação vs. validação de esquema
Um formatador verifica se o JSON é sintaticamente válido — chaves balanceadas, strings corretamente entre aspas, sem vírgulas finais. Ele não verifica se os dados fazem sentido: se um campo que deveria ser um número é na verdade uma string, ou se falta um campo obrigatório. Isso é uma preocupação separada, tratada pela validação de JSON Schema, que verifica estrutura e tipos contra uma definição de esquema em vez de apenas verificar que o JSON em si está bem formado.
Um fluxo de trabalho para JSON bagunçado ou quebrado
- Cole o JSON bruto — minificado, quebrado, ou de outra forma — primeiro em um formatador.
- Se ele for analisado, revise a estrutura recuada em busca do campo ou valor que você realmente procura.
- Se falhar ao ser analisado, verifique primeiro a localização do erro: a maioria dos parsers reporta uma linha/coluna, que geralmente aponta diretamente para uma vírgula, chave ou aspa faltante.
- Preste atenção especial a vírgulas finais e aspas tipográficas quando a fonte foi digitada à mão ou colada de um editor que não é de código.
Erros comuns a evitar
- Presumir que recuo com aparência válida significa JSON válido — formatação e análise são etapas separadas.
- Adicionar uma vírgula final por hábito vindo de JavaScript ou Python, onde ela é frequentemente tolerada.
- Colar JSON de um processador de texto e obter aspas tipográficas curvas em vez de retas.
- Confundir "formata sem erro" com "corresponde ao esquema esperado pela API" — essas são verificações diferentes.
A maioria dos erros JSON é um caractere específico em um lugar específico — o verdadeiro valor de um formatador é tornar esse lugar visível em vez de deixar você vasculhar uma única linha ininterrupta para encontrá-lo.