Boas Práticas de Formatação JSON Que Todo Desenvolvedor Deve Conhecer

Os Fundamentos da Estrutura JSON

JSON (JavaScript Object Notation) é um formato de texto leve para representar dados estruturados. Apesar do nome, é independente de linguagem e usado em todo lugar, desde APIs REST até arquivos de configuração. Um documento JSON válido é um objeto (um conjunto de pares chave-valor entre chaves) ou um array (uma lista ordenada entre colchetes).

Os seis tipos de valor em JSON são: string, number, boolean (true/false), null, object e array. Cada chave em um objeto JSON deve ser uma string entre aspas duplas — não aspas simples, não identificadores sem aspas.

Erros de Sintaxe Comuns

JSON é rígido. Um único erro de sintaxe torna o documento inteiro impossível de analisar. Os erros mais frequentes são:

• Vírgulas finais: {"name": "Alice",} — a vírgula após o último item é ilegal em JSON (é válida em JavaScript, o que causa confusão).
• Strings com aspas simples: JSON exige aspas duplas. {'key': 'value'} não é um JSON válido.
• Chaves sem aspas: {name: "Alice"} é sintaxe de objeto literal JavaScript, não JSON.
• Comentários: JSON não suporta comentários. Se precisar de comentários em um arquivo de configuração, considere JSONC ou YAML.
• Undefined e NaN: Esses valores JavaScript não existem em JSON. Use null ou omita o campo.
• Caracteres de controle não escapados: Quebras de linha dentro de strings devem ser escritas como \n, não como quebras de linha literais.

Formatação para Legibilidade

O JSON enviado pela rede geralmente é minificado — sem espaços em branco — para reduzir o tamanho do payload. Mas o JSON armazenado em arquivos de configuração ou versionado deve ser formatado para legibilidade humana. As convenções padrão são:

• Dois ou quatro espaços por nível de indentação (escolha um e seja consistente)
• Um par chave-valor por linha em objetos
• Chave de abertura na mesma linha que a chave pai, chave de fechamento em sua própria linha
• Arrays de valores simples podem ser escritos em uma única linha se forem curtos

A maioria dos editores consegue formatar JSON automaticamente. No VS Code, clique com o botão direito e selecione "Formatar Documento", ou use o atalho Shift+Alt+F. Usuários de linha de comando podem usar jq . input.json para formatar qualquer arquivo JSON.

Convenções de Nomenclatura

O próprio JSON não impõe convenções de nomenclatura, mas sua API ou base de código deve escolher uma e mantê-la. Os três padrões comuns são:

• camelCase (firstName) — padrão em APIs JavaScript e na maioria dos serviços REST
• snake_case (first_name) — comum em APIs Python e PostgreSQL
• PascalCase (FirstName) — usado em alguns ambientes .NET e C#

Misturar convenções em uma única API é fonte de confusão. Se você consome uma API com uma convenção e sua base de código usa outra, trate a conversão em uma camada de serialização dedicada em vez de espalhar conversões ad-hoc por todo o seu código.

Lidando com Campos Nulos vs. Ausentes

Um objeto JSON pode representar a ausência de um valor de duas formas: a chave está presente com valor null, ou a chave está completamente ausente. Elas têm semânticas diferentes. Use null quando um campo é esperado mas não tem valor (por exemplo, um campo de nome do meio que o usuário deixou em branco). Omita o campo quando ele simplesmente não se aplica a aquele registro. Decida por uma abordagem consistente dentro da sua API para que os consumidores saibam o que esperar.

Números Grandes e Precisão

Os números JSON não têm limite de tamanho definido, mas muitos parsers os desserializam como valores de ponto flutuante de precisão dupla IEEE 754. Isso significa que inteiros maiores que 2^53 não podem ser representados com precisão. Se o seu JSON precisa carregar inteiros grandes (IDs de banco de dados, valores financeiros em unidades monetárias menores, identificadores criptográficos), represente-os como strings e documente isso na sua API. Esse é um problema bem conhecido com os IDs de tweets do Twitter, por exemplo.

Validando JSON

Além da validação de sintaxe (este JSON é válido?), o JSON Schema permite definir a estrutura esperada de um documento: quais campos são obrigatórios, seus tipos, intervalos de valores e mais. Ferramentas como ajv (JavaScript), jsonschema (Python) e validadores online podem verificar um documento JSON em relação a um esquema. Para qualquer API que você publica ou consome em um contexto de produção, a validação com JSON Schema vale a pena ser implementada na fronteira.

Um formatador e validador JSON — como o do TheDailyUtils — é a forma mais rápida de identificar erros de sintaxe em um payload desconhecido. Cole o JSON bruto e você verá imediatamente se ele é válido e onde estão os erros.

Formate e Valide JSON Instantaneamente

Abra o formatador JSON gratuito — cole qualquer JSON para formatar, minificar ou identificar erros de sintaxe em segundos. Funciona no seu navegador; seus dados ficam privados.