Guia de Formatação JSON

JSON é o formato dominante de intercâmbio de dados na web moderna. Simples na superfície — um punhado de tipos primitivos, objetos com chaves string e arrays — mas sua rigidez pega desenvolvedores todo dia. Este guia cobre a estrutura, as armadilhas de sintaxe que falham na validação, quando formatar vs minificar, e as variantes mais soltas que você vai encontrar.

Estrutura JSON

Todo documento JSON é um objeto (envolto em { } com pares chave–valor separados por vírgula) ou um array (envolto em [ ] com valores separados por vírgula). Valores são strings (entre aspas duplas), números, booleanos (true/false), null, objetos ou arrays. Chaves devem sempre ser strings entre aspas duplas — nunca aspas simples, nunca identificadores sem aspas.

Erros de sintaxe que custam horas

• Vírgulas finais — [1, 2, 3,] é válido em JavaScript mas ilegal em JSON.
• Aspas simples — {'chave': 'valor'} é JavaScript, não JSON. Chaves e valores string exigem aspas duplas.
• Comentários — JSON não tem sintaxe de comentário. // nota ou /* bloco */ fazem JSON.parse falhar.
• Chaves sem aspas — {nome: "Daytics"} falha. Correto: {"nome": "Daytics"}.
• Caracteres de controle em strings — quebras de linha, tabs ou nulls literais dentro de string sem escape.
• NaN e Infinity — não são números JSON válidos. Serialize como string ou null.

Pretty-print vs minificar

JSON formatado é para humanos: indentação e quebras de linha ajudam a ler estrutura e comparar valores. Use em arquivos de configuração, documentação e logs de depuração. JSON minificado é para máquinas: tudo em uma linha, sem espaços, payload mínimo. Use quando o JSON trafega pela rede ou é armazenado em escala. A maioria das ferramentas alterna com uma chamada (JSON.stringify(obj, null, 2) pretty, JSON.stringify(obj) minificado).

JSON5 e JSONC

Quando você precisa de comentários e vírgulas finais, existem dois supersetes comuns. JSON5 permite strings entre aspas simples, chaves sem aspas, comentários, vírgulas finais, hex e strings multilinha. JSONC — usado pelo VS Code — é mais estrito: apenas adiciona comentários ao JSON puro. Nenhum é universalmente parseado; converta para JSON estrito antes de enviar pela rede.

Tamanho e desempenho

Minificar JSON formatado corta 15–30% do tamanho. A compressão gzip achata essa diferença — para JSON servido por HTTP, gzip costuma ganhar da minificação. Para localStorage, IndexedDB e payloads móveis restritos, minificar continua importando — cada byte conta.

Validar como hábito

Quando um sistema rejeitar seu JSON, cole num validador antes de editar. Nove em cada dez erros são uma vírgula final despercebida, uma aspa simples acidental ou um caractere de controle perdido. Um validador aponta linha e coluna exatas, poupando a meia-hora de inspeção visual.