Melhores práticas de formatação JSON — indentação, legibilidade e os debates que não morrem

A gramática do JSON é mínima. Seis tipos de valores, sem comentários, sem vírgulas finais, sem flexibilidade em como as strings são citadas. Essa rigidez é sua força para máquinas e sua fraqueza para humanos. Quando um humano precisa ler ou escrever JSON — em um arquivo de configuração, resposta de API, diff — a formatação importa.

Esta publicação cobre toda decisão de formatação que você enfrentará, o que o ecossistema decidiu e onde os debates ainda ferozem.

Indentação: 2 espaços é o vencedor

A guerra de Tabulações vs Espaços tem um vencedor na terra do JSON: 2 espaços. Quase todo guia de estilo, linter e formatador usa indentação de 2 espaços por padrão:

• Guia de Estilo JSON do Google — 2 espaços
• Prettier — 2 espaços (padrão)
• ESLint — 2 espaços (maioria das configurações)
• AWS CloudFormation — 2 espaços
• Manifestos do Kubernetes — 2 espaços

A razão é prática: JSON já é verboso com suas aspas e chaves. Indentação de 4 espaços empurra objetos aninhados para fora da borda direita da maioria dos editores. 2 espaços mantém as coisas legíveis sem desperdiçar espaço horizontal.

Use 4 espaços se sua equipe preferir e você for consistente. Use tabulações se precisar, mas esteja ciente de que a maioria das ferramentas JSON assume espaços, e indentação misturada em um arquivo JSON é um erro de análise esperando acontecer.

Vírgulas finais: ainda não

JSON não permite vírgulas finais. Este é o erro de sintaxe mais comum em arquivos JSON editados manualmente. Você escreve:

{
  "name": "Alice",
  "items": ["a", "b",],
}

E um parser rigoroso o rejeita. A vírgula final após "b" e a vírgula final após a chave fechante } são ambas ilegais.

YAML permite vírgulas finais (e a maioria das linguagens faz). JSON não. Se suas ferramentas suportam JSONC (JSON com Comentários, usado no tsconfig.json e settings.json do VS Code), vírgulas finais são permitidas. Mas JSON puro — o tipo que viaja por APIs — não as tolera.

A melhor defesa: use um formatador que detecte isso automaticamente. Cole seu JSON em um validador antes de commitar.

Bonito vs compacto

JSON bonito tem quebras de linha e indentação. É legível, tem diff e é debugável:

{
  "status": "ok",
  "count": 42
}

JSON compacto não tem espaço em branco entre tokens. É menor na rede:

{"status":"ok","count":42}

A regra geral:

• Voltado para humanos (arquivos de configuração, logs, respostas de API durante debug) → bonito.
• Voltado para máquinas (payloads de API em produção, filas de mensagens, streams de eventos) → compacto.
• Armazenamento (banco de dados, caches) → compacto, a menos que você precise ler manualmente durante debug.

JSON compacto economiza aproximadamente 20-30% em tamanho comparado a JSON bonito de 2 espaços. Para um payload de 10KB, são 2-3KB. Sobre milhões de requisições, isso se acumula. Para um arquivo de configuração que você edita manualmente, a legibilidade do JSON bonito vale os bytes extras.

Chaves ordenadas

As chaves de objeto devem ser ordenadas alfabeticamente?

A favor: diffs são determinísticos. Se você adicionar uma chave, apenas essa linha aparece em um diff do git. Sem chaves ordenadas, inserir uma chave no meio pode deslocar cada chave subsequente, criando um diff barulhento.

Contra: agrupamento lógico é mais legível. Colocar "name" primeiro e "id" segundo é intuitivo. Ordenação alfabética coloca "address" antes de "name" sem razão semântica.

A resposta pragmática: ordene chaves em JSON gerado por máquina (APIs, configs, diffs). Mantenha a ordem lógica em JSON escrito à mão. A maioria dos formatadores (Prettier, jq, python -m json.tool) tem uma flag --sort-keys que você pode habilitar no CI.

Convenções de nomes de chaves

As chaves de JSON são strings, e o ecossistema se estabeleceu em duas convenções:

• camelCase — o padrão JavaScript/Node.js. firstName, lastName, createdAt.
• snake_case — o padrão Python/Ruby/Rust. first_name, last_name, created_at.
• kebab-case — raro em JSON, mais comum em URLs e CSS. Evite para chaves de API.

Escolha uma e mantenha. A maioria das APIs usa camelCase. Se você está construindo uma API REST para consumidores de JavaScript, camelCase é o caminho de menor resistência. Se está interfaceando com serviços Python, snake_case reduz a fricção.

A pior coisa que você pode fazer é misturar: firstName em um endpoint, last_name em outro. Escolha uma convenção, force com um linter e siga em frente.

Formatação de números

JSON não distingue inteiros de floats. 42 e 42.0 são ambos válidos, e a maioria dos parsers os trata identicamente. Mas formatação importa para legibilidade:

• Inteiros: sem ponto decimal. 42, não 42.0.
• Floats: use tantos dígitos quanto necessário. 3.14159, não 3.14159000000000.
• Números grandes: use notação científica se o número for enorme. 1e10 é mais claro que 10000000000.

JSON não suporta Infinity, -Infinity ou NaN. Se sua linguagem serializa esses, a saída não é JSON válido e parsers o rejeitarão.

Strings: aspas simples vs duplas

JSON requer aspas duplas para strings. Isso não é negociável. 'hello' não é JSON válido. "hello" é.

Se seu linter ou editor permite aspas simples em arquivos JSON, está analisando JSONC ou um superconjunto, não JSON padrão. APIs e parsers que esperam JSON rigoroso rejeitarão strings com aspas simples.

Comentários: ainda não permitidos

JSON não tem sintaxe de comentários. Isso é por design (a especificação diz que JSON é “um formato de troca de dados”, não uma linguagem de configuração), mas é a reclamação mais comum de desenvolvedores que usam YAML.

Soluções alternativas:

• Use uma chave "comment" ou "_comment". É feio, mas válido.
• Use JSONC (formato do VS Code) se suas ferramentas suportarem.
• Mude para YAML ou TOML para arquivos de configuração onde comentários importam.

O fluxo de trabalho do formatador

O melhor fluxo de trabalho para formatação JSON:

1. Escreva JSON como quiser. Não perca tempo indentando à mão.
2. Execute um formatador ao salvar. Prettier, jq ou o formatador embutido do seu editor.
3. Commite a saída formatada. Diffs consistentes, sem debates de estilo.
4. Valide no CI. Um passo de lint JSON detecta vírgulas finais e erros de sintaxe antes que cheguem à produção.

Isso elimina todo debate de formatação. O formatador decide, todos os outros escrevem código.

Erros comuns

• Vírgulas finais — o erro de análise mais frequente em JSON editado manualmente.
• Aspas simples — válidas em literais de objeto JavaScript, inválidas em JSON.
• Chaves sem aspas — { name: "Alice" } é JavaScript, não JSON.
• Comentários — // isso não é JSON nem /* isso também não */.
• Indentação misturada — misturar tabulações e espaços no mesmo arquivo.

Cole seu JSON em um validador antes de implantar. Leva um segundo e economiza trinta minutos debugando um erro 400 misterioso.