O que é JSON? Um guia em linguagem simples (e como corrigir erros comuns)

JSON está em toda parte no software moderno — arquivos de configuração, respostas de API, bancos de dados e ajustes dependem dele. Ainda assim, uma única vírgula perdida pode quebrar um arquivo inteiro e deixar você encarando um críptico erro «Unexpected token». Este guia explica o que é JSON em linguagem simples, como sua sintaxe realmente funciona e como diagnosticar e corrigir os erros que você mais vai encontrar.

O que é JSON

JSON significa JavaScript Object Notation. É um formato leve, baseado em texto, para armazenar e trocar dados estruturados. Apesar do nome, não está preso ao JavaScript — praticamente toda linguagem de programação consegue lê-lo e escrevê-lo, que é exatamente por que ele virou a língua padrão das APIs web.

Todo o propósito do JSON é ser legível tanto por humanos quanto por máquinas. Ele representa os dados como uma combinação de alguns blocos simples:

• Objetos — coleções de pares chave/valor envoltos em chaves { }.
• Arrays — listas ordenadas envoltas em colchetes [ ].
• Valores — uma string, um número, true, false, null, um objeto ou um array.

Aqui um exemplo pequeno, mas completo:

{
  "name": "Ada Lovelace",
  "active": true,
  "age": 36,
  "skills": ["math", "logic"],
  "address": {
    "city": "London",
    "postcode": null
  }
}

As regras que fazem tropeçar

JSON parece muito com um objeto JavaScript, e essa semelhança é a fonte da maioria dos erros — JSON é mais rígido. Tenha essas regras em mente e você evitará a grande maioria dos erros:

1. Chaves e strings precisam de aspas duplas

Toda chave deve ser uma string em aspas duplas, e todo valor de texto também deve usar aspas duplas. Aspas simples não são JSON válido, mesmo que sejam aceitáveis em JavaScript.

// Inválido
{ 'name': 'Ada' }

// Válido
{ "name": "Ada" }

2. Sem vírgulas finais

Você não pode deixar uma vírgula após o último item de um objeto ou array. Este é o erro de JSON mais comum, porque muitos editores e linguagens o permitem sem reclamar em outros lugares.

// Inválido — vírgula após o último valor
{ "a": 1, "b": 2, }

// Válido
{ "a": 1, "b": 2 }

3. Sem comentários

O JSON padrão não tem sintaxe de comentários. Linhas que começam com // ou blocos entre /* */ causam um erro de análise. Se você precisa de comentários, formatos como JSON5 ou YAML os permitem — veja nosso formatador de YAML se isso encaixa melhor no seu caso.

4. Números são simples

Números são escritos sem aspas e sem zeros à esquerda ou pontos decimais no final. 01, 1. e .5 são todos inválidos; escreva 1, 1.0 e 0.5.

Erros comuns e como corrigi-los

Quando um parser rejeita seu JSON, ele geralmente informa uma linha e uma coluna. Esse local aponta onde o parser desistiu, o que muitas vezes fica logo depois do erro real. Aqui estão as mensagens que você mais verá e o que elas realmente significam:

• "Unexpected token } in JSON" — quase sempre uma vírgula final antes da chave ou do colchete de fechamento. Remova a vírgula extra.
• "Unexpected string" / "Expected comma" — falta uma vírgula entre dois valores, ou você usou uma quebra de linha onde deveria ir uma vírgula.
• "Unexpected token ' in JSON" — aspas simples. Troque-as por aspas duplas.
• "Unexpected end of JSON input" — um colchete ou chave nunca foi fechado. Conte seus { e }; cada abertura precisa de um fechamento correspondente.
• "Unexpected token o in JSON" — um sinal clássico de que você tentou analisar algo que já era um objeto, não uma string JSON. Chame um parser apenas em texto.

A forma mais rápida de cravar o ponto exato é passar o texto por um formatador que valida à medida que avança. Nosso formatador e validador de JSON destaca a linha e a coluna precisas do primeiro erro e, quando o JSON está válido, imprime-o formatado para que problemas estruturais (um colchete fora do lugar, um valor aninhado um nível a mais) fiquem óbvios de relance. Tudo roda no seu navegador, então você pode conferir dados privados ou sensíveis com segurança.

Formatar vs. minificar

Duas operações surgem o tempo todo ao trabalhar com JSON. Formatar (também chamado de embelezar ou pretty-print) adiciona indentação e quebras de linha para tornar um bloco denso legível — ideal ao depurar. Minificar remove todo espaço e quebra de linha desnecessários para produzir a menor saída possível — ideal para enviar pela rede ou embutir em código, quando o tamanho importa. Os dados são idênticos nos dois casos; só o espaço em branco muda.

Checklist rápido

Antes de entregar JSON a um programa, verifique:

• Todas as chaves e valores de string usam aspas duplas.
• Não há vírgulas finais.
• Não há comentários.
• Cada colchete e chave está balanceado.
• Passa em um validador sem erros.

Acerte esses cinco e o JSON se torna o que foi projetado para ser: um formato chato, previsível e que simplesmente funciona. Quando algo escapa, cole-o no formatador de JSON e deixe que ele aponte direto para o problema.