O que é um arquivo JSON?

JSON é um formato de texto puro que abre em qualquer editor. Ele é usado para mover dados entre programas e a web.

A extensão é .json e o nome por extenso é JavaScript Object Notation. Os dois importam menos do que aquilo que o arquivo consegue carregar, e é disso que trata o resto desta página.

Ele remonta a 2001. A especificação é RFC 8259.

A idade interessa por um motivo prático: quanto mais antigo o formato, mais programas tiveram tempo de aprendê-lo.

Ela está publicada por inteiro, então dá para implementá-la a partir do documento em vez de por observação — é por isso que o formato aparece em tantos programas e por isso que arquivos escritos há vinte anos ainda abrem. Especificação publicada não é o mesmo que livre de royalties: quando o formato embrulha um codec, o licenciamento das patentes é uma questão à parte, que a norma não resolve.

JSON guarda o conteúdo exatamente. Salvar de novo não muda nada, então dá para abrir, editar e salvar quantas vezes você quiser sem acumular estrago — e é isso que faz dele um formato de trabalho e não de entrega.

JSON não tem sintaxe de comentário. Tudo que explica precisa morar fora do arquivo, e é bom saber disso antes de escolhê-lo para algo que uma pessoa vai editar na mão.

Visual Studio Code, jq e Postman leem esse formato, e a maioria dos programas do mesmo tipo também.

Quando um arquivo não abre, o formato raramente é o problema — mais comum é o programa ser mais antigo que ele. Converter para algo mais antigo é o caminho confiável, e é para isso que serve o resto deste site.

Qualquer navegador atual lê o formato.

Dá para colocá-lo numa página ou anexá-lo a uma mensagem sem se perguntar o que o outro lado tem instalado.

JSON foi feito para ser aberto e alterado. Mantenha o arquivo nesse formato enquanto o trabalho estiver em andamento e exporte a partir dele sempre que precisar de uma cópia pronta.

Um documento JSON é construído com objeto, array, string, número, booleano e nulo. Esse é o vocabulário inteiro, e a brevidade da lista é o motivo do formato ter dominado: toda linguagem de programação já tem os seis, então ler um documento significa chamar uma função e receber valores nativos sem precisar mapear nada.

A especificação cabe em poucas páginas. Foi descrita em vez de desenhada — Douglas Crockford pegou a sintaxe de objeto literal que o JavaScript já tinha e escreveu o que já funcionava — motivo pelo qual parece óbvia em vez de engenhosa.

JSON não tem comentário, de propósito, e é a propriedade mais reclamada do formato. O raciocínio era que comentário convida diretiva de interpretação, e o resultado é que o JSON é uma linguagem de configuração pobre por melhor formato de transmissão que seja.

Três soluções alternativas circulam. Uma chave chamada algo como "_comment", que todo interpretador aceita e todo validador de esquema rejeita. JSON5 e JSONC, que acrescentam comentário e vírgula sobrando e não são JSON — o arquivo de configuração do Visual Studio Code é JSONC. E a resposta honesta, que é usar TOML ou YAML para qualquer coisa que uma pessoa mantém.

JSON não distingue inteiro de ponto flutuante. A maioria dos interpretadores lê todo número como um double, e um double guarda inteiros exatamente só até cerca de nove quatrilhões.

Depois disso, valores mudam silenciosamente. Um identificador de banco de dados de 64 bits, um valor financeiro grande na menor unidade — tudo pode voltar como um número diferente do que foi enviado, sem erro nenhum. O remédio é enviar esses valores como string, o que toda API séria faz, e vale conferir em vez de presumir ao integrar com uma que talvez não faça.

Chaves duplicadas não são proibidas. Interpretadores diferem no que fazem — a maioria mantém a última, alguns mantêm a primeira, poucos dão erro — e um documento que depende de qualquer um desses comportamentos está dependendo de uma implementação, não do JSON.

A ordem das chaves também não tem garantia de ser preservada, então tratar um objeto como estrutura ordenada é um erro; use um array se a ordem importar. E não existe data: a convenção universal é uma string ISO 8601, e todo interpretador entrega uma string que outra coisa precisa interpretar.

JSON é UTF-8. A especificação diz isso para qualquer coisa trocada entre sistemas, e o corolário prático é que uma marca de ordem de byte não é permitida — esses três bytes invisíveis no início de um arquivo causam uma falha de interpretação cuja mensagem geralmente culpa o primeiro caractere em vez de nomear a causa.

Se um arquivo JSON falha ao interpretar e parece perfeito num editor, isso é a primeira coisa a checar. "UTF-8 sem BOM" é o ajuste, e é o mesmo conselho de todo outro formato de texto deste site, com a diferença de que aqui é genuinamente fatal em vez de apenas irritante.

Um documento JSON precisa estar completo antes de poder ser interpretado — o colchete de fechamento é o que o torna válido — então um array de dez gigabytes de registros precisa ser lido inteiro na memória antes do primeiro estar disponível. Para grandes exportações e pipelines de log isso é fatal.

O NDJSON, também chamado JSON Lines, resolve isso colocando um objeto JSON completo em cada linha sem array ao redor. Cada linha interpreta independentemente, então um arquivo de qualquer tamanho flui linha por linha, e um processo pode começar a trabalhar no primeiro registro imediatamente. Exportação de dados e pipeline de log quase sempre usam isso.

JSON Schema é o jeito padrão de descrever a cara de um documento válido, e vale usar em qualquer interface entre dois sistemas — transforma "a API retornou algo estranho" num erro específico nomeando o campo. O suporte é bom e menos uniforme que o equivalente em XML.

Para o trabalho cotidiano, um editor com suporte a JSON dá a metade importante de graça: uma vírgula faltando ou sobrando é sinalizada no lugar, e JSON gerado por máquina que chegou como uma linha longa única pode ser formatado em algo legível. Os dois são operações de dois segundos que economizam um tempo surpreendente.