O que é JSON? Um guia completo para iniciantes

Se você já construiu um site, chamou uma API ou espiou um arquivo package.json, já conhece JSON. Significa JavaScript Object Notation, e é basicamente a linguagem universal que os aplicativos usam para se comunicar. Não se deixe enganar pelo "JavaScript" — JSON funciona com praticamente todas as linguagens de programação.

Vamos explicar tudo em linguagem simples, com muitos exemplos pelo caminho.

Uma breve lição de história

JSON foi criado por Douglas Crockford no início dos anos 2000. Ele queria algo mais simples que XML para enviar dados entre navegadores e servidores. A ideia pegou rápido — JSON foi oficialmente padronizado como ECMA-404 em 2013 e depois como RFC 8259 em 2017.

Hoje, mais de 90% das APIs web usam JSON. Não vai a lugar nenhum.

Como o JSON se parece?

Aqui está um exemplo simples — um objeto JSON representando uma pessoa:

Bem legível, né? Esse é o objetivo. Vamos ver as regras que fazem isso funcionar.

As regras de sintaxe (são simples, prometo)

Tipos de dados: JSON oferece seis blocos de construção para trabalhar: strings (sempre entre aspas duplas), números, booleanos (true/false), null, objetos e arrays. É isso — sem datas, sem funções, sem tipos especiais.

Objetos: São seus pares chave-valor, envolvidos em chaves {}. As chaves devem ser strings entre aspas duplas. Aqui está um exemplo de objeto aninhado:

Arrays: Listas ordenadas entre colchetes []. Podem conter qualquer combinação de tipos:

Cuidado: JSON não permite vírgulas no final. Então {"name": "Sam",} vai quebrar seu parser. Isso pega muita gente que vem do JavaScript, onde vírgulas no final são perfeitamente aceitáveis.

Por que os desenvolvedores amam JSON

Existem algumas razões pelas quais JSON venceu a guerra dos formatos de dados:

• É extremamente simples. Compare {"name": "Jo"} com o Jo do XML. Menos digitação, menos ruído.
• Todas as linguagens suportam. Python tem json.loads(), JavaScript tem JSON.parse(), Go tem encoding/json — já deu pra entender. Confira a documentação JSON no MDN para o lado do JavaScript.
• É leve. Payloads JSON são tipicamente 30-50% menores que o XML equivalente. Isso importa quando você está enviando milhões de respostas de API por dia.
• Mapeia naturalmente para o código. Um objeto JSON parece quase idêntico a um dicionário Python, um objeto JavaScript ou um hash Ruby. Sem necessidade de camada de tradução.

Onde você encontra JSON por aí

• APIs web: Chame quase qualquer API REST e você receberá JSON de volta. Experimente você mesmo — abra seu navegador e visite https://api.github.com/users/octocat. Isso é JSON.
• Arquivos de configuração: package.json para Node.js, tsconfig.json para TypeScript, settings.json para VS Code — JSON está em todo lugar nas ferramentas de desenvolvimento.
• Bancos de dados: MongoDB armazena dados em BSON (JSON binário). PostgreSQL tem tipos de coluna JSON nativos. Até o MySQL adicionou suporte a JSON.
• Troca de dados: Microserviços quase sempre se comunicam em JSON via HTTP.

JSON vs XML — A versão curta

XML ainda tem seu lugar (mais sobre isso no nosso artigo sobre XML), mas para a maioria do trabalho de desenvolvimento web, JSON ganha em legibilidade, tamanho de arquivo e velocidade de parsing. A única área onde o XML brilha? Dados centrados em documentos com conteúdo misto, schemas e transformações.

Validando seu JSON

Até um erro minúsculo — uma vírgula faltando, aspas extras ou uma vírgula no final — faz o parsing de JSON falhar completamente. Não existe "parsing parcial" com JSON; ou funciona ou não funciona. Por isso ferramentas como nosso JSON Formatter e JSON Validator são tão úteis. Cole seu JSON e você verá instantaneamente se algo está errado.

Erros comuns em JSON (e como corrigi-los)

Depois de anos trabalhando com JSON, aqui estão os erros que vejo desenvolvedores cometerem repetidamente:

1. Aspas simples em vez de aspas duplas. Isso é JavaScript válido, mas NÃO é JSON válido:

2. Vírgulas no final. JavaScript permite, JSON não:

3. Comentários. JSON não tem sintaxe de comentários. Se você precisa de comentários em arquivos de configuração, considere usar JSONC (JSON with Comments, suportado pelo VS Code) ou mude para YAML.

4. Chaves sem aspas. Em JavaScript você pode escrever {name: "Sarah"}, mas em JSON toda chave deve ser uma string entre aspas: {"name": "Sarah"}.

5. Usar undefined. O undefined do JavaScript não existe em JSON. Use null em vez disso.

Trabalhando com JSON em diferentes linguagens

Uma das maiores forças do JSON é o suporte universal de linguagens. Veja como o parsing e a serialização funcionam em linguagens populares:

Percebeu como as APIs são parecidas? parse/loads para ler, stringify/dumps para escrever. A maioria das linguagens segue esse mesmo padrão.

Dicas de performance para JSON

Quando você está lidando com payloads JSON grandes, a performance começa a importar. Aqui vão algumas dicas práticas:

• Minifique para produção. Remover espaços em branco do JSON pode reduzir o tamanho do arquivo em 10-30%. Nosso JSON Minifier faz isso em um clique.
• Use parsers de streaming para arquivos grandes. Se seu arquivo JSON tem centenas de megabytes, não carregue tudo na memória. Bibliotecas como JSONStream (Node.js) ou ijson (Python) fazem parsing incremental.
• Evite estruturas profundamente aninhadas. Cada nível de aninhamento adiciona overhead ao parsing. Se você está aninhando mais de 4-5 níveis, considere achatar seu modelo de dados.
• Considere alternativas binárias para casos extremos. Para sistemas de altíssimo throughput, formatos como MessagePack, BSON ou Protocol Buffers podem oferecer payloads 2-5x menores e parsing mais rápido. Mas você perde a legibilidade humana, então é uma troca.

JSON no design de APIs do mundo real

Vamos ver como APIs reais estruturam suas respostas JSON. Aqui está um padrão comum para respostas de API paginadas:

E aqui está um padrão comum de resposta de erro:

Esses padrões são tão comuns que você os verá em quase toda API REST bem projetada. Seguir convenções como essas torna sua API mais fácil de entender para outros desenvolvedores.

Referência rápida de JSON

Aqui está uma folha de consulta com tudo que você pode colocar em um documento JSON:

Experimente você mesmo

Pronto para colocar esse conhecimento em prática? Aqui estão as ferramentas que você vai querer salvar nos favoritos:

• JSON Formatter — Cole JSON bagunçado e obtenha-o lindamente formatado com indentação correta.
• JSON Validator — Verifique rapidamente se seu JSON é sintaticamente válido e receba mensagens de erro claras quando não for.
• JSON Minifier — Remova espaços em branco do seu JSON para payloads de produção.

JSON pode parecer simples na superfície, mas dominar suas peculiaridades e melhores práticas vai economizar incontáveis horas de depuração. Agora vá e construa algo incrível!