O que é JSON? Sintaxe, erros comuns e como validar

JSON (JavaScript Object Notation) é um formato leve, baseado em texto, para armazenar e trocar dados estruturados, construído com objetos de pares chave/valor, arrays ordenados e alguns tipos de valor: strings, números, true, false e null. É o formato padrão das APIs web e de muitos arquivos de configuração porque é fácil de ler para as pessoas e simples de interpretar em qualquer linguagem de programação. O JSON é rígido: chaves e strings precisam de aspas duplas, e vírgulas finais e comentários não são permitidos.

Como é um JSON: exemplo

O JSON nasceu da sintaxe que o JavaScript usa para literais de objeto, mas é independente de linguagem. Ele é definido na RFC 8259 e no padrão ECMA-404, e o resumo de uma página em json.org descreve toda a gramática. Um documento típico é assim:

{
  "id": 1042,
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "active": true,
  "score": 98.5,
  "manager": null,
  "roles": ["admin", "editor"],
  "address": {
    "city": "London",
    "postcode": "N1 9GU"
  }
}

Os espaços em branco entre os elementos (espaços, tabulações e quebras de linha) são ignorados, então os mesmos dados podem ser escritos em uma só linha ou distribuídos com indentação. O nível superior de um documento JSON pode ser qualquer valor, embora as APIs quase sempre usem um objeto ou um array.

Tipos de dados do JSON

Não existe tipo de data. As datas costumam ser escritas como strings no formato ISO 8601, como "2026-10-13T09:30:00Z", ou como timestamps Unix em números; nosso Conversor de timestamp Unix converte de um para o outro.

Números e precisão

O padrão JSON não limita o tamanho nem a precisão dos números, mas os programas que o leem limitam. O JavaScript armazena números como valores de ponto flutuante de 64 bits, então inteiros maiores que 9.007.199.254.740.991 (2⁵³ − 1) podem perder precisão sem aviso. Para IDs grandes, muitas APIs os enviam como strings, por exemplo "id": "1234567890123456789".

Regras de sintaxe do JSON que mais causam erros

O JSON parece JavaScript, dicionários do Python e YAML, e é justamente por isso que as pessoas escrevem JSON inválido sem querer. Estas regras não têm exceções no JSON padrão:

• As chaves precisam ser strings entre aspas duplas. {name: "Ada"} é JavaScript válido, mas JSON inválido; escreva {"name": "Ada"}.
• Somente aspas duplas. 'Ada' não é uma string JSON.
• Sem vírgulas finais. [1, 2, 3,] e {"a": 1,} são inválidos.
• Sem comentários. Nem // ... nem /* ... */ são permitidos.
• Os valores literais ficam em minúsculas. True, FALSE e None (a grafia do Python) são inválidos; use true, false e null.
• Sem undefined, funções ou números especiais. Eles existem no JavaScript, mas não têm equivalente em JSON.
• As chaves devem ser únicas. O padrão diz que os nomes dentro de um objeto devem ser únicos; com duplicatas, os parsers se comportam de formas diferentes, e muitos mantêm silenciosamente só a última.

Algumas ferramentas aceitam variantes mais flexíveis. Arquivos como o settings.json do VS Code e o tsconfig.json do TypeScript são lidos por parsers que permitem comentários (muitas vezes chamados de JSONC), e o JSON5 permite comentários, aspas simples e vírgulas finais. São formatos separados: um parser JSON padrão, inclusive o que seu cliente de API ou seu servidor usa, vai rejeitá-los.

Erros comuns de JSON e como corrigi-los

A redação dos erros varia entre parsers. A tabela mostra o tipo de mensagem que você verá no módulo json do Python ou no JSON.parse de um navegador, o que ela costuma significar e a correção. A posição informada muitas vezes aponta para logo depois do erro real, então olhe também o caractere anterior.

A última linha é uma das mais frequentes na prática: o código chama JSON.parse ou response.json() em uma página de erro que começa com <!DOCTYPE html>, e o < é apontado como token inesperado.

JSON vs YAML vs XML

O YAML 1.2 foi projetado para que documentos JSON sejam, salvo raros casos extremos, também YAML válido, o que torna simples converter entre os dois. Nosso Conversor JSON ↔ YAML faz os dois sentidos, o Formatador e validador de YAML e o Formatador e validador de XML validam os outros dois formatos, e o Conversor CSV ↔ JSON transforma exportações de planilhas em arrays de objetos.

Como formatar e minificar JSON

Como os espaços em branco não têm significado, o mesmo JSON pode ser formatado para humanos ou para máquinas:

• O JSON formatado (pretty-printed) acrescenta quebras de linha e indentação, normalmente de dois ou quatro espaços, para que o aninhamento fique visível. Use-o em arquivos de configuração, documentação e depuração.
• O JSON minificado remove todo o espaço em branco opcional para deixar a carga menor. Use-o em dados enviados pela rede ou armazenados em grande volume; a compressão HTTP também reduz o tamanho, então a economia costuma ser modesta.

{"name":"Ada","roles":["admin","editor"],"active":true}

A maioria das linguagens faz as duas coisas. Em JavaScript, JSON.stringify(data, null, 2) formata com indentação de dois espaços e JSON.stringify(data) minifica. Em Python, json.dumps(data, indent=2) formata e json.dumps(data, separators=(",", ":")) gera a saída mais compacta.

Como validar JSON

Validar JSON tem dois níveis: se ele é sintaticamente um JSON válido e se tem a estrutura que sua aplicação espera.

1. Confira a sintaxe com um parser rígido. Cole o texto no nosso Formatador e validador de JSON, que informa a linha e a coluna do primeiro erro e roda no seu navegador. Na linha de comando, python3 -m json.tool data.json ou jq . data.json imprime o documento formatado ou um erro.
2. Corrija os erros um de cada vez. O parser para no primeiro problema, então execute-o de novo depois de cada correção até não haver mais erros.
3. Confira a estrutura. Confirme que os campos obrigatórios existem e têm os tipos certos, seja no código ou com um validador de JSON Schema.
4. Confira a codificação. O JSON trocado entre sistemas deve ser UTF-8. Um arquivo salvo em outra codificação pode gerar caracteres estranhos ou erros em textos que não estão em inglês.

JSON Schema em resumo

JSON Schema é um vocabulário, escrito no próprio JSON, para descrever como é um documento válido: quais propriedades são obrigatórias, de que tipo cada uma deve ser, valores permitidos, padrões de string, intervalos numéricos e assim por diante. Existem validadores para a maioria das linguagens, e formatos de descrição de API como o OpenAPI usam JSON Schema para descrever corpos de requisição e resposta. A especificação está publicada em json-schema.org. Um pequeno exemplo:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "email"],
  "properties": {
    "id": { "type": "integer", "minimum": 1 },
    "email": { "type": "string", "format": "email" },
    "roles": { "type": "array", "items": { "type": "string" } }
  }
}

Um documento sem email ou com um id do tipo string seria um JSON válido, mas falharia neste schema. Observe que muitos validadores tratam format como uma anotação e não o validam, a menos que sejam configurados para isso.

Perguntas frequentes

O JSON pode ter comentários?

Não. O JSON padrão não permite comentários de nenhum tipo. Algumas ferramentas aceitam JSONC ou JSON5, que permitem, mas arquivos destinados a serem lidos por outros programas devem usar JSON puro. Se precisar de uma observação, adicione um campo como "_comment".

Por que o JSON não permite vírgulas finais?

A gramática foi mantida deliberadamente mínima e simplesmente não as inclui. Muitos mecanismos JavaScript e outras linguagens aceitam vírgulas finais na sua própria sintaxe, e é por isso que elas aparecem com frequência, por engano, em JSON escrito à mão.

Qual é a diferença entre JSON e um objeto JavaScript?

O JSON é um formato de texto; um objeto JavaScript é uma estrutura de dados na memória. A sintaxe do JSON é um subconjunto mais rígido da sintaxe de literais do JavaScript. Você converte de um para o outro com JSON.parse e JSON.stringify.

O que significa "Unexpected token < in JSON at position 0"?

O texto que está sendo interpretado começa com <, o que quase sempre significa que você recebeu HTML, como uma página de erro ou de login, em vez de JSON. Verifique a URL da requisição, o código de status HTTP e o corpo bruto da resposta.

A ordem das chaves em um objeto JSON é preservada?

O padrão trata os objetos como não ordenados, então você não deve depender da ordem das chaves. Na prática, a maioria dos parsers modernos mantém a ordem em que leu, mas a ordem dos arrays é a única que o JSON garante.

Qual extensão de arquivo e tipo MIME o JSON usa?

Os arquivos usam a extensão .json e o tipo de mídia é application/json, conforme registrado na RFC 8259.