Como formatar e validar JSON sem quebrá-lo

JSON parece simples até uma vírgula faltando derrubar um deploy. A maioria das falhas de JSON não é exótica: são vírgulas sobrando, aspas simples, comentários ou um colchete que não fecha. Este guia mostra o que um JSON válido realmente permite, os erros mais comuns e uma forma confiável de formatar e validar um payload.

O que um JSON válido permite

JSON tem uma gramática bem pequena:

• Um valor é um objeto, array, string, número, true, false ou null.
• As chaves de objeto precisam ser strings entre aspas duplas.
• Strings usam aspas duplas; aspas simples não são válidas.
• Arrays e objetos não podem ter vírgula sobrando.
• Comentários não fazem parte da especificação JSON.
• Números não podem ser NaN, Infinity ou hexadecimal.

É basicamente isso. O rigor é o ponto: todo interpretador de JSON, em qualquer linguagem, consegue concordar sobre a mesma entrada.

Os cinco erros mais comuns

1. Vírgulas sobrando

{
  "name": "Ada",
  "age": 36,
}

Isso é válido em JavaScript e em JSON5, mas não em JSON. Remova a vírgula depois da última propriedade.

2. Aspas simples

{ 'name': 'Ada' }

JSON só aceita aspas duplas. Isso costuma acontecer quando você copia de Python ou JavaScript manualmente.

3. Chaves sem aspas

{ name: "Ada" }

Chaves de objeto precisam ser strings entre aspas duplas. É outro hábito do JavaScript que o JSON não tem.

4. Comentários

{
  // o nome do usuário
  "name": "Ada"
}

JSON não tem comentários. Se você precisa de comentários em um arquivo de configuração, use JSONC ou YAML, mas não envie comentários para uma API JSON.

5. Colchetes que não fecham

Um } ou ] faltando costuma gerar erro no fim do arquivo, e não onde o problema está de fato. Formatar o documento deixa o nível que falta muito mais fácil de enxergar.

Por que formatar importa

JSON minificado é eficiente para máquinas, mas penoso para pessoas. Um documento formatado:

• mostra a estrutura de relance;
• deixa os diffs legíveis na revisão de código;
• ajuda a encontrar um colchete ou uma vírgula faltando;
• dá uma forma estável para comparar dois payloads.

Se você está depurando uma resposta de API, cole no formatador antes de ler. Se está comparando duas versões, formate as duas primeiro e depois compare. Formatar remove o ruído de espaços e deixa a mudança real visível.

Embelezar vs. minificar

Embelezar adiciona indentação e quebras de linha para facilitar a leitura. Minificar remove todo espaço opcional para transporte. São os mesmos dados; escolha pelo público:

• Use o formato embelezado para logs, documentação, fixtures de teste e depuração.
• Use JSON minificado em corpos de requisição e resposta onde cada byte conta.

Um formatador deve permitir alternar entre 2 espaços, 4 espaços, tabulações e saída minificada sem mudar os valores.

Encontrando erros com linha e coluna

A mensagem de erro mais útil não é “JSON inválido”; é “token inesperado na linha 4, coluna 3”. Interpretadores modernos costumam informar a posição, mas o formato da mensagem varia conforme o runtime.

Um formatador no navegador consegue interpretar o documento, informar linha e coluna e manter a saída vazia até o JSON ser válido. Esse ciclo de feedback é muito mais rápido do que adivinhar qual colchete falta.

O Formatador de JSON faz exatamente isso: cole um payload, veja a posição do erro e formate ou minifique quando ele for válido. Tudo roda localmente, então você pode usar com payloads de produção sem risco.

JSON não é um objeto JavaScript

Um objeto literal JavaScript pode conter funções, undefined, chaves com aspas simples e comentários. JSON não pode. A confusão é comum porque a sintaxe parece parecida, mas JSON é um formato de dados, não uma linguagem.

Se você precisa transformar JSON em um valor JavaScript, JSON.parse resolve. Se precisa transformar um objeto JavaScript em JSON, JSON.stringify vai:

• descartar undefined e funções;
• converter datas em strings;
• lançar erro em referências circulares;
• transformar NaN e Infinity em null.

Conhecer essas regras evita toda uma classe de bugs do tipo “por que este campo desapareceu?”.

De JSON para outros formatos

Depois que um payload é válido, muitas vezes você precisa dele em outro formato:

• JSON para CSV transforma um array de objetos em planilha.
• YAML para JSON leva configurações entre os dois formatos.
• Comparador de Textos compara um payload antigo e um novo depois de formatar os dois.

Uma checklist prática

1. Cole o payload em um formatador e corrija os erros de sintaxe primeiro.
2. Formate as duas versões antes de compará-las.
3. Minifique só quando estiver prestes a enviar os dados.
4. Deixe comentários fora do JSON; use YAML ou JSONC em configurações que precisam deles.
5. Não use JSON para segredos que você não colocaria em um log.

JSON é rígido de propósito. Depois que você conhece as poucas regras que ele impõe, a maioria dos erros de interpretador fica óbvia em segundos.