O que é JSON? O formato em que seus dados chegam quando você os baixa

JSON significa JavaScript Object Notation, um nome enganoso — hoje tem pouco a ver com JavaScript e é usado por tudo. É um jeito de escrever dados estruturados em texto puro, e é o que você recebe quando pede a um serviço que exporte sua conta, quando um app guarda suas configurações e quando um programa manda dados para outro.

Com o que se parece

Um exemplo pequeno contém quase tudo que o formato sabe fazer:

{
  "name": "Widget",
  "price": 4.50,
  "inStock": true,
  "tags": ["small", "blue"],
  "discount": null
}

Chaves contêm um objeto — um conjunto de valores nomeados. Colchetes contêm um array — uma lista ordenada. E esse é todo o sistema de tipos: objetos, arrays, textos, números, true/false e null. Seis coisas.

Objetos e arrays podem conter uns aos outros em qualquer profundidade, e é assim que o JSON descreve estruturas complicadas com um vocabulário tão pequeno.

As regras que pegam as pessoas

• Só aspas duplas. 'name' é inválido. Todo texto e toda chave precisam de aspas duplas.
• Chaves precisam de aspas. name: "Widget" é inválido; "name": "Widget" é o certo.
• Sem vírgula final. Uma vírgula depois do último item quebra o arquivo. É o erro de JSON mais comum.
• Sem comentários. Nenhum — nem //, nem /* */. É a ausência mais reclamada da história do formato, e foi deliberada: comentários convidam a colocar sentido onde os analisadores não olham.
• UTF-8. Chinês, japonês e acentos não são problema; salve o arquivo como UTF-8.

A proibição de comentários tem um contorno universal: acrescente uma chave comum como "_comment" com sua nota como valor. Não é um comentário — programas vão ler como dado — mas é onde todo mundo põe explicações num arquivo de configuração.

Uma vírgula faltando quebra tudo

O JSON não tem como se recuperar de um erro de sintaxe. Não há fronteiras de registro como as linhas de um CSV, então um analisador que encontra algo inesperado não pode pular a parte ruim e seguir — o arquivo inteiro falha.

Pior, o número de linha informado é onde o analisador percebeu, não onde você errou. Esqueça uma chave de fechamento perto do topo e o erro aparece no fim do arquivo, porque é o primeiro ponto em que a estrutura se tornou impossível. Esqueça uma vírgula e a mensagem costuma apontar a linha seguinte à que precisa ser corrigida.

Então quando um erro de JSON nomeia uma linha, olhe a estrutura acima dela, não a linha em si. Um validador, ou um editor que destaque parênteses correspondentes, acha isso bem mais rápido que a leitura.

Por que substituiu o XML para dados

O primeiro ponto é peso. Em XML um valor vem embrulhado numa tag de abertura e numa de fechamento; em JSON é um nome, dois-pontos e o valor. Num arquivo grande isso é uma diferença considerável de tamanho e legibilidade.

O segundo importa mais: os seis tipos do JSON mapeiam diretamente nas estruturas de dados que toda linguagem de programação já tem. Um objeto vira dicionário, um array vira lista, um número é um número. XML exige interpretação — tudo é texto até algo decidir o que significa.

O que o JSON abre mão em troca é tudo que tem a ver com documentos: sem comentários, sem atributos, sem namespaces e sem jeito de representar texto com marcação dentro. É por isso que dados viajam em JSON e documentos ficam em XML.

Converter para planilha

Um array plano de objetos converte limpo. Uma lista de registros com os mesmos campos é uma tabela: uma linha por objeto, uma coluna por chave.

Dados aninhados não. Se cada registro contém um array de outros objetos — um pedido com vários itens, um usuário com vários endereços — não há jeito honesto de pôr isso numa grade. A conversão ou achata em colunas chamadas items.0.name, items.1.name, ou descarta o aninhamento.

Não é limitação do conversor. Uma planilha é um retângulo e o JSON é uma árvore, e árvores não cabem em retângulos. Quando os dados são de fato aninhados, o movimento útil costuma ser extrair como lista plana exatamente a parte de que você precisa, em vez de converter a estrutura toda.

JSON Lines, para exportações grandes

Uma exportação grande muitas vezes não é um documento JSON, mas um arquivo com um objeto JSON completo por linha, conhecido como JSONL ou NDJSON.

A razão é prática: um único array gigante precisa ser lido inteiro na memória antes de qualquer coisa, e nada pode ser acrescentado sem reescrever o arquivo. Um objeto por linha pode ser processado linha a linha e estendido para sempre.

Se um arquivo tem .jsonl ou .ndjson, ou abre como muitas linhas cada uma começando com {, é isso — e entregá-lo a um analisador JSON comum vai falhar, porque o arquivo como um todo não é JSON válido.

É um arquivo de texto

Tudo que vale sobre Markdown nesse ponto vale aqui. JSON abre em qualquer editor de texto, sobrevive ao desaparecimento de qualquer software, é pesquisável com ferramentas comuns e compara linha a linha entre versões.

O único passo prático é formatá-lo antes de ler. JSON exportado costuma chegar como uma única linha enorme. Qualquer formatador ou editor decente o reindenta em algo legível, sem mudar os dados.

Consulta rápida

• Seis tipos de valor: objeto, array, texto, número, true/false, null
• Só aspas duplas, chaves com aspas, sem vírgula final, sem comentários
• Use uma chave "_comment" quando precisar deixar uma nota
• Um erro de sintaxe mata o arquivo inteiro; a linha informada é onde foi notado, não onde quebrou
• Arrays planos de objetos viram planilha; dados aninhados não
• JSONL é um objeto por linha — para exportações grandes, e não é JSON válido como um todo
• Formate antes de ler; por baixo é texto puro