GameParticles
Desenvolvimento

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. // note e /* note */ são erros.
  • Os literais são em minúsculas: true, false, null. True, NULL e undefined são inválidos.
  • Números não podem ter zeros à esquerda (007), um sinal de mais na frente (+5), nem ser NaN ou Infinity.
  • 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.

Ferramentas deste guia

Perguntas frequentes

Por que meu JSON falha com Unexpected token at position N?

O parser chegou a um caractere que não esperava naquela posição. Olhe um token antes dela: uma vírgula sobrando, uma aspa simples ou um colchete de fechamento faltando é quase sempre a causa.

Comentários são permitidos em JSON?

Não. Nem // nem /* */ fazem parte da gramática do JSON. Algumas ferramentas os aceitam em arquivos de configuração (JSONC, JSON5), mas um parser padrão, como o JSON.parse, vai rejeitá-los.

Formatar JSON é o mesmo que validar?

Formatar reindenta um JSON válido para facilitar a leitura. Validar confere a sintaxe. Um formatador precisa primeiro fazer o parsing do texto, então ele valida como efeito colateral, mas não confere os seus dados em relação a um schema.

Como converto a saída de um dict do Python em JSON de verdade?

Use json.dumps(obj) no Python em vez de str(obj). A forma str usa aspas simples e literais do Python, como True e None, que não são JSON válido.

Mais guias para desenvolvedores

Formatador de JSON
Desenvolvimento · Formate, valide e minifique JSON com realce de sintaxe.
↵
Codificar / decodificar Base64
Desenvolvimento · Codifique texto em Base64 ou decodifique Base64 para texto simples.
↵
Codificador / Decodificador de URL
Desenvolvimento · Codifique ou decodifique componentes de URL e query strings.
↵
Gerador de hash
Desenvolvimento · Gere hashes MD5, SHA-1, SHA-256 e SHA-512.
↵
Gerador de UUID
Desenvolvimento · Gere UUIDs v4 (aleatórios) em massa com um clique.
↵
Testador de regex
Desenvolvimento · Teste expressões regulares em um texto com destaque das correspondências ao vivo.
↵
Contador de palavras
Texto · Conte palavras, caracteres, frases, parágrafos e tempo de leitura.
↵
Conversor de maiúsculas e minúsculas
Texto · Converta texto para MAIÚSCULAS, minúsculas, Título, camelCase, snake_case e mais.
↵
Ordenador de listas
Texto · Ordene, inverta, embaralhe e remova duplicatas de listas de texto.
↵
Prévia de Markdown
Texto · Escreva em Markdown e veja a prévia renderizada ao vivo, lado a lado.
↵
Calculadora de porcentagem
Números · Calcule porcentagens, aumentos, reduções e quantos % um número é de outro.
↵
Conversor de cores
Cores · Converta cores entre HEX, RGB, HSL e HSV na hora.
↵
Snake
Arcade · Coma, cresça e não bata nas paredes. Um clássico atemporal.
↵
2048
Quebra-cabeça · Deslize e combine as peças até chegar à lendária peça 2048.
↵
Word Grid
Quebra-cabeça · Adivinhe a palavra oculta de cinco letras em seis tentativas com pistas de cores.
↵
Sudoku
Quebra-cabeça · Preencha a grade 9x9 com lógica. Quatro níveis, do fácil ao especialista.
↵
Campo Minado
Estratégia · Use as pistas numéricas para limpar o campo minado. Lógica clássica, três níveis.
↵
Breakout
Arcade · Quebre todos os tijolos com raquete e bola. Power-ups, combos e níveis sem fim.
↵
Treino de digitação
Casual · Melhore seu PPM e sua precisão com treinos de 30 segundos a 5 minutos. Descubra suas teclas fracas.
↵
TypeRunner
Arcade · Corrida de digitação multiplayer. Desafie amigos por link, vença o computador ou persiga o seu fantasma.
↵
Typing Blocks
Arcade · Digite cada palavra antes que o bloco de madeira pouse. Se errar, a pilha sobe em direção à linha.
↵
Bubble Shooter
Arcade · Mire, rebata nas paredes e estoure grupos de três ou mais bolhas.
↵
Road Rush
Arcade · Corra contra sete rivais no trânsito e abra caminho no soco.
↵