Melhores Práticas de JSON que Todo Desenvolvedor Deveria Conhecer

O JSON (JavaScript Object Notation) se tornou a linguagem universal de troca de dados na web. Praticamente toda API REST, arquivo de configuração e pipeline de dados usa JSON. Apesar da sua simplicidade, há muitas formas de escrever JSON bem ou mal. Este guia reúne as melhores práticas de JSON mais importantes, que vão deixar suas APIs mais limpas, seu código mais fácil de manter e seus sistemas mais performáticos.

1. Use Convenções de Nomenclatura Consistentes

A fonte mais comum de confusão em APIs JSON é a nomenclatura inconsistente das chaves. Escolha uma convenção e mantenha-a em toda a sua API:

• camelCase (firstName, userId) — Preferida em JavaScript e na maioria das APIs web (incluindo as APIs do Google, Stripe e GitHub).
• snake_case (first_name, user_id) — Comum em APIs Python e Ruby, e em muitos sistemas baseados em banco de dados.
• kebab-case (first-name) — Raramente usada em JSON, pois hifens exigem chaves entre aspas no JavaScript.

Seja qual for a sua escolha, aplique-a universalmente. Misturar user_id e userId na mesma API é uma das inconsistências mais frustrantes que um consumidor pode encontrar.

2. Sempre Use Aspas Duplas em Chaves e Valores de String

A especificação do JSON (RFC 8259) exige que chaves e valores de string estejam entre aspas duplas. Aspas simples não são JSON válido. Essa é uma pegadinha comum ao converter objetos literais de JavaScript para JSON, já que o próprio JavaScript permite aspas simples.

{'name': 'Pan Tool', 'free': true}

{"name": "Pan Tool", "free": true}

3. Use os Tipos de Dados Adequados

O JSON suporta seis tipos de dados: string, number, boolean, null, array e object. Use o tipo que corresponde semanticamente ao dado — não use strings para tudo.

• Use boolean true/false, e não as strings "true"/"false" nem os números 1/0 para valores booleanos.
• Use null para a ausência intencional de um valor. Não use strings vazias "" nem 0 para representar "sem valor".
• Use números para quantidades numéricas, e não strings como "42".
• Use arrays para coleções ordenadas de itens do mesmo tipo.
• Use strings no formato ISO 8601 para datas: "2025-04-15T10:30:00Z". O JSON não tem um tipo nativo de data.

4. Projete um Envelope de Resposta Consistente

Em APIs REST, sempre envolva a sua resposta em uma estrutura de envelope consistente. Isso torna o tratamento de erros previsível para os consumidores:

{
  "success": true,
  "data": {
    "id": 42,
    "name": "Pan Tool"
  },
  "meta": {
    "total": 1,
    "page": 1
  }
}

// Em caso de erro:
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "O recurso solicitado não foi encontrado."
  }
}

Envelopes consistentes permitem que os consumidores da sua API escrevam um único utilitário de tratamento de respostas, em vez de lidar com formatos de resposta diferentes para cada endpoint.

5. Valide o JSON Antes de Processá-lo

Nunca presuma que o JSON recebido é válido. Sempre valide tanto a sintaxe (é um JSON válido?) quanto a estrutura (contém os campos esperados?) antes de processá-lo.

• Em PHP, verifique json_last_error() === JSON_ERROR_NONE após chamar json_decode().
• Em JavaScript/Node.js, envolva JSON.parse() em um try/catch.
• Use bibliotecas de validação com JSON Schema para validar estrutura, tipos e campos obrigatórios de forma sistemática.

6. Minifique o JSON em Produção, Formate em Desenvolvimento

Em desenvolvimento e em arquivos de configuração versionados, use JSON formatado com indentação para facilitar a leitura. Nas respostas de API em produção, sirva JSON minificado para reduzir o tamanho do payload.

Um arquivo de configuração JSON bem formatado com 500 linhas pode ter 20 KB. O equivalente minificado pode ter 12 KB — uma redução de 40%. Quando servido via HTTPS com compressão GZIP, o JSON minificado comprime ainda melhor do que o JSON formatado.

Use nosso Minificador de JSON gratuito para comprimir JSON para produção, e nosso Formatador de JSON para expandir JSON minificado na hora de ler e editar.

7. Evite Estruturas Profundamente Aninhadas

JSON com aninhamento profundo é difícil de ler, difícil de consultar e, muitas vezes, um sinal de modelagem de dados ruim. Como regra geral, tente manter a profundidade do seu JSON em no máximo 3 a 4 níveis. Se você se pegar aninhando objetos em 6 ou 7 níveis, geralmente é um sinal de que vale repensar o seu modelo de dados.

{
  "user": {
    "profile": {
      "address": {
        "billing": {
          "country": { "code": "US" }
        }
      }
    }
  }
}

{
  "user_id": 42,
  "billing_country_code": "US"
}

8. Trate Números Grandes com Cuidado

O JSON.parse() do JavaScript usa ponto flutuante de precisão dupla IEEE 754 para todos os números, o que só consegue representar com segurança inteiros até 2^53 - 1 (9.007.199.254.740.991). IDs e timestamps maiores do que isso perdem precisão ao serem interpretados em JavaScript.

A solução: para IDs inteiros grandes (como os snowflake IDs do Twitter), retorne tanto a representação numérica quanto a de string: "id": 944985814402506752, "id_str": "944985814402506752". Consumidores que precisam de precisão podem usar a string.

9. Use null para Campos Opcionais Ausentes

Quando um campo existe no seu schema mas não tem valor para um recurso específico, inclua-o explicitamente como null em vez de omiti-lo. Omitir campos dificulta distinguir entre "este campo não existe no schema" e "este campo existe, mas não tem valor". A presença consistente dos campos torna as respostas da API previsíveis.

10. Versione a Sua API

À medida que a sua API evolui, você precisará fazer mudanças incompatíveis na estrutura do seu JSON. Planeje isso desde o primeiro dia versionando a sua API, seja pelo caminho da URL (/api/v1/users), por parâmetro de query (?version=2) ou pelo cabeçalho Accept (Accept: application/vnd.yourapi.v2+json).