O que é JSON e por que ele virou o formato padrão da web

JSON é um formato de texto para guardar e trocar dados estruturados, e virou o padrão da web porque é simples o bastante para uma pessoa ler e rigoroso o bastante para qualquer linguagem interpretar sem ambiguidade. A sigla vem de JavaScript Object Notation, mas hoje Python, Java, PHP, Go, C# e praticamente todo o resto leem e escrevem JSON com uma linha de código.

Um exemplo de cadastro de cliente:

{
  "id": 58,
  "nome": "Mariana Souza",
  "ativo": true,
  "limite": 1500.50,
  "telefones": ["12 99999-0000", "12 3333-4444"],
  "endereco": { "cidade": "Lorena", "uf": "SP" },
  "observacao": null
}

Ali estão os seis tipos que o JSON aceita: texto (sempre entre aspas duplas), número, booleano (true ou false), null, array (lista entre colchetes) e objeto (pares chave e valor entre chaves). Não existe tipo data, não existe comentário, não existe função. Essa pobreza proposital é exatamente o que deixou o formato universal.

A gramática inteira cabe numa página, e a versão em português está no site oficial json.org, com a especificação em português. Na internet, o formato é padronizado pela RFC 8259, o padrão do JSON na IETF, que exige UTF-8 quando o JSON trafega entre sistemas.

Por ser tão rígido, um caractere fora do lugar invalida o arquivo inteiro. E é aí que a maioria dos iniciantes perde tempo. Os erros abaixo respondem por quase todos os “Unexpected token” que você vai encontrar.

Vírgula sobrando depois do último item quebra o arquivo inteiro

JavaScript moderno aceita vírgula no fim de listas e objetos. JSON não aceita.

{
  "nome": "Teclado",
  "preco": 199.90,   <- esta vírgula derruba o parse
}

O custo desse erro costuma aparecer longe da origem: o arquivo de configuração foi editado à mão, o deploy sobe e a aplicação não inicia, com uma mensagem apontando a linha seguinte, a da chave de fechamento. Quando o erro indica a linha de um } ou ], olhe primeiro a linha anterior.

Aspas simples e chaves sem aspas não são JSON

Quem vem de JavaScript ou Python escreve {'nome': 'Ana'} ou {nome: "Ana"} sem pensar. Os dois são inválidos. Em JSON, toda chave e todo texto usam aspas duplas, sem exceção.

Uma armadilha específica de Python: imprimir um dicionário com print() mostra aspas simples, True e None. Aquilo é a representação do Python, não JSON. Copiar essa saída para outro sistema dá erro. Para gerar JSON de verdade, use o módulo padrão:

import json

cliente = {"nome": "Ana", "ativo": True, "obs": None}
texto = json.dumps(cliente, ensure_ascii=False)
print(texto)   # {"nome": "Ana", "ativo": true, "obs": null}

O ensure_ascii=False mantém “ã” e “ç” legíveis em vez de virar ã. Os dois formatos são válidos, mas o primeiro é mais fácil de conferir a olho. A documentação do módulo json do Python lista as outras opções, como indent=2 para formatar.

Comentários no meio do arquivo fazem o parser recusar tudo

Parece natural deixar um // porta do banco de produção num arquivo de configuração. O padrão não prevê comentários, e o parser rejeita o arquivo.

Alguns arquivos que parecem JSON aceitam comentário, como o tsconfig.json e as configurações do VS Code, porque essas ferramentas usam leitores mais tolerantes (o chamado JSONC). Isso confunde: o mesmo comentário funciona ali e quebra num package.json. Se precisar documentar um campo, use uma chave própria, como "_comentario": "...", ou documente fora do arquivo.

Confiar no JSON.parse sem try/catch derruba a tela

No navegador e no Node.js, JSON.parse() transforma texto em objeto e JSON.stringify() faz o caminho inverso. A referência está na MDN, na página do objeto global JSON do JavaScript. O ponto que pouca gente trata: se o texto vier inválido, JSON.parse lança exceção, e sem tratamento o código para ali.

let config;
try {
  config = JSON.parse(textoRecebido);
} catch (erro) {
  console.error("JSON inválido:", erro.message);
  config = {};   // segue com um padrão seguro
}

Pista de ouro: “Unexpected token <” no parse quase nunca é erro no seu JSON. É o servidor devolvendo HTML no lugar dele.

Isso acontece muito quando uma API está fora do ar e devolve uma página HTML de erro em vez de JSON. A mensagem “Unexpected token <” quase sempre significa isso: o primeiro caractere recebido foi o < de um <html>. Antes de procurar erro no seu código, veja o status da resposta e o cabeçalho Content-Type.

Datas e números grandes chegam diferentes do que saíram

Este erro não quebra o arquivo. Ele corrompe o dado em silêncio, e por isso é o mais caro da lista.

Datas viram texto

Como JSON não tem tipo data, cada sistema escolhe um formato. Um manda "06/11/2026", outro "2026-11-06T14:30:00Z", um terceiro um número de segundos. Combine sempre o formato ISO 8601 com fuso horário explícito. Data sem fuso é a origem de pedidos que “mudam de dia” quando passam pelo servidor.

Números muito grandes perdem precisão

JavaScript representa números como ponto flutuante de 64 bits, que só garante inteiros exatos até 9.007.199.254.740.991. IDs gerados por alguns bancos e redes sociais passam disso. O resultado: o ID chega ao navegador com os últimos dígitos trocados e a busca não encontra o registro. A solução comum é trafegar esses IDs como texto. Para dinheiro, o raciocínio é parecido: muitas APIs mandam centavos como inteiro (15050 em vez de 150.50) para evitar arredondamentos.

Codificação errada transforma acento em ruído

Você já viu “São Paulo” no lugar de “São Paulo”. Isso é texto UTF-8 sendo lido como se fosse Latin-1, problema clássico de sistemas brasileiros antigos e de arquivos salvos pelo Excel. Como o padrão exige UTF-8 na troca entre sistemas, salve e leia sempre nessa codificação e declare Content-Type: application/json; charset=utf-8 nas respostas da sua API.

JSON contra XML, CSV e YAML: por que ele venceu na web

Os concorrentes não desapareceram; cada um ficou no seu nicho. A comparação ajuda a entender por que o JSON dominou as APIs:

A vantagem decisiva do JSON foi nascer colado ao JavaScript, a linguagem do navegador. Quando as aplicações web passaram a buscar dados sem recarregar a página, trocar JSON ficou mais leve e mais simples do que montar e ler XML. As APIs seguiram o navegador, e o resto do ecossistema seguiu as APIs.

Um exemplo bem brasileiro de convivência: a NF-e continua em XML, mas muitos sistemas de emissão expõem APIs em JSON e fazem a conversão por dentro. Se você vai integrar algo assim, o texto sobre como integrar consulta de dados de empresas em sistemas mostra o tipo de resposta JSON que essas APIs devolvem na prática.

Um hábito que evita a maioria desses erros

• Gere JSON sempre pelo serializador da linguagem, nunca à mão.
• Envolva todo parse de dado externo em tratamento de exceção.
• Combine o formato de datas (ISO 8601 com fuso) e trafegue IDs grandes como texto.
• Salve e leia em UTF-8.

Desses quatro, o primeiro merece um exemplo. Nunca monte JSON concatenando texto à mão, com '{"nome": "' + nome + '"}'. Basta um nome com aspas, como Bar do “Zé”, para o resultado ficar inválido. Use sempre o serializador da linguagem (json.dumps, JSON.stringify, Jackson, Gson) e valide arquivos editados à mão no editor ou com python -m json.tool arquivo.json antes do commit. Se o JSON aparece ao lado de outros termos que você ainda está aprendendo, como API, endpoint e REST, o glossário de programação do portal liga cada um deles.