Como formatar e validar JSON (e corrigir os erros mais comuns)
Aprenda a formatar, validar e minificar JSON, ler erros do parser e corrigir os culpados de sempre: vírgulas sobrando, aspas simples e texto sem escape.
Atualizado
Formatar JSON significa reindentá-lo para que cada chave fique em sua própria linha; validar significa conferir se ele segue exatamente a gramática do JSON. Cole o texto em um formatador, leia o primeiro erro que ele apontar, corrija só aquilo e rode de novo. A maior parte dos JSONs quebrados tem um de cerca de seis erros, e todos estão listados abaixo.
O que um JSON válido realmente exige
O JSON é mais rigoroso que os literais de objeto do JavaScript, e é aí que começa a maior parte da confusão. As regras que importam:
- As chaves precisam ser strings entre aspas duplas:
{"a":1}é válido,{a:1}e{'a':1}não são. - Valores de string usam apenas aspas duplas.
"it's"está certo;'single'não está. - Nada de vírgulas sobrando no final.
[1,2,3,]falha;[1,2,3]passa. - Nada de comentários.
// notee/* note */são erros. - Os literais são em minúsculas:
true,false,null.True,NULLeundefinedsão inválidos. - Números não podem ter zeros à esquerda (
007), um sinal de mais na frente (+5), nem serNaNouInfinity. - O nível superior pode ser qualquer valor, mas a maioria das APIs espera um objeto
{}ou um array[].
Se você tiver essas sete regras em mente, normalmente consegue achar o problema no olho. Quando não conseguir, um validador dá a posição exata.
Como ler um erro do parser
Todo parser de JSON informa a posição em que desistiu, não necessariamente onde está o erro. Unexpected token } in JSON at position 42 significa que o parser chegou a um } quando esperava outra coisa, normalmente porque a linha anterior termina com uma vírgula sobrando. Unexpected end of JSON input significa que um colchete, uma chave ou uma aspa foi aberto e nunca fechado. Unexpected token ' quase sempre significa aspas simples.
A abordagem prática: olhe a posição informada e depois olhe um token para trás. O Formatador de JSON sinaliza o erro no próprio texto, naquela posição, para que você não precise contar caracteres.
Corrigindo os erros comuns
Vírgulas sobrando
Copiar de JavaScript, de dicts do Python ou de arquivos de configuração editados à mão deixa uma vírgula depois do último item. Apague a vírgula antes de cada } e ]. Os linters a permitem em JS; o JSON, nunca.
Aspas simples e chaves sem aspas
A saída de print(dict) do Python, {'name': 'Ada', 'age': 36}, parece JSON, mas não é. Troque ' por " e coloque aspas em todas as chaves soltas. Se a origem for Python, use json.dumps() em vez de str() para obter JSON de verdade.
Caracteres sem escape dentro de strings
Uma aspa dupla literal ou uma quebra de linha dentro de uma string precisa de escape: "She said \"hi\"" e "line one\nline two". As próprias barras invertidas viram \\, então um caminho do Windows é "C:\\Users\\ada". Tabulações são \t, e qualquer ponto de código Unicode pode ser escrito como \u00e9.
Codificação e caracteres invisíveis
Uma marca de ordem de bytes (BOM) no início de um arquivo, aspas tipográficas coladas de um documento ou um espaço não separável entre tokens produzem erros confusos em uma linha que parece limpa. Redigite as aspas suspeitas e salve o arquivo como UTF-8 sem BOM.
Documentos concatenados ou embrulhados
Arquivos de log muitas vezes contêm um objeto JSON por linha. O arquivo inteiro não é JSON válido; cada linha é. Separe pelas quebras de linha e faça o parsing de cada linha separadamente, ou envolva as linhas em [ e ] com vírgulas entre elas. Da mesma forma, uma resposta de API embrulhada em um callback como cb({...}) é JSONP, então remova primeiro a chamada de função.
Formatação legível versus minificação
O JSON formatado para leitura usa dois ou quatro espaços por nível de aninhamento e uma chave por linha, que é o que você quer para leitura, diffs e arquivos de configuração versionados no git. O JSON minificado elimina todos os espaços em branco e fica em uma única linha, que é o que você quer no tráfego de rede ou dentro de uma variável de ambiente. Os dois são os mesmos dados. JSON.stringify(obj, null, 2) formata para leitura em JavaScript; JSON.stringify(obj) minifica. Em Python, json.dumps(obj, indent=2) faz o mesmo trabalho.
Formatar nunca muda o significado, mas a ordem das chaves não é garantida pela especificação do JSON. Não escreva código que dependa de {"b":1,"a":2} continuar nessa ordem depois de uma ida e volta.Validando em relação a um schema
A validação de sintaxe só diz que o texto é um JSON bem formado. Ela não diz que "age" é um número nem que "email" está presente. Para isso você precisa de JSON Schema, com um validador como o Ajv em JavaScript ou o jsonschema em Python. Comece pela sintaxe, porque um validador de schema não consegue rodar sobre um texto que não passa pelo parser.
Convertendo de e para outros formatos
Planilhas querem linhas e colunas, não objetos aninhados. Um array de objetos planos, como [{"id":1,"name":"Ada"},{"id":2,"name":"Lin"}], mapeia de forma limpa para CSV com uma linha de cabeçalho, e o conversor de JSON para CSV lida com campos entre aspas e vírgulas embutidas nos dois sentidos. Objetos aninhados precisam ser achatados primeiro.
Arquivos de configuração de Kubernetes, GitHub Actions e Docker Compose normalmente são YAML. Todo documento JSON também é YAML válido, mas o inverso não é verdade, já que o YAML permite comentários, âncoras e strings sem aspas. Quando um arquivo YAML se comporta mal, convertê-lo com o conversor de YAML para JSON mostra exatamente como o parser interpretou cada valor, o que revela a surpresa clássica de yes virar true ou de 3.10 virar 3.1.
As demais ferramentas de formatação, codificação e validação ficam na categoria de desenvolvedor.
Experimente
Cole o seu JSON com falha no Formatador de JSON. Ele roda no seu navegador, destaca o erro na posição exata e permite alternar entre a saída formatada e a minificada com uma largura de indentação personalizada.