Formatador JSON

O que este formatador aceita

O parser segue a RFC 8259 à risca, o que é mais rígido do que a maioria espera. As chaves precisam de aspas duplas. Strings usam aspas duplas, nunca simples. Não pode haver vírgula depois do último elemento de um objeto ou array, não existe sintaxe de comentário de nenhum tipo, e não existem NaN, Infinity nem undefined. Números não podem ser escritos em hexadecimal, não podem ter sinal de mais na frente e não podem ter zero à esquerda na parte inteira.

Essa rigidez é proposital, não preciosismo: é a regra que todo parser JSON do outro lado vai aplicar. Um documento que formata aqui vai ser lido em Python, Go, Rust e PostgreSQL. Um documento que só funciona depois que um parser tolerante adivinha a sua intenção vai falhar em algum lugar mais tarde, geralmente em produção.

Se a entrada tem comentários ou vírgulas finais, ela não é JSON, e sim JSON5 ou JSONC, as variantes flexíveis usadas por arquivos de configuração como o tsconfig.json. São formatos reais, com usos reais, e remover os comentários para deixar o documento como JSON válido é uma edição que perde informação. Faça isso sabendo o que está fazendo.

Como ler o erro

Quando a análise falha, o erro traz linha e coluna, calculadas a partir da posição de caractere informada pelo motor. Repare que a posição indica onde o parser desistiu, e nem sempre onde você errou: uma chave de fechamento faltando costuma ser informada no fim do documento, porque tudo até ali ainda podia ser válido.

Quatro causas respondem por quase todas as falhas: uma vírgula antes de um colchete ou chave de fechamento, aspas simples em volta de uma string ou chave, uma chave sem aspas copiada de um objeto literal JavaScript, e aspas duplas ou quebra de linha sem escape dentro de um valor de string. Se a coluna informada aponta para um caractere de aspas, a string anterior provavelmente terminou antes da hora.

Documentos truncados são o outro caso comum. Uma resposta cortada por limite de tamanho ou timeout é analisada sem problemas até parar no meio de um valor, então o erro cai na última linha, e não num lugar que ajude. Verifique o fim da entrada antes de procurar no meio.

O que muda na ida e volta

Formatar significa analisar o documento e serializá-lo de novo, então algumas coisas são normalizadas no caminho, e vale saber quais.

Números viram doubles IEEE 754. Qualquer inteiro maior que 9.007.199.254.740.991 perde precisão, o que importa porque IDs de banco de 64 bits, IDs snowflake no estilo do Twitter e timestamps em nanossegundos ficam todos acima desse limite. Um ID 9223372036854775807 volta como 9223372036854776000. Se você precisa desses valores intactos, mantenha-os como strings no payload. Zeros à direita também somem: 1.0 vira 1, e 1e3 vira 1000.

Chaves duplicadas se fundem, prevalecendo a última, porque a etapa de análise monta um objeto. Fora isso a ordem das chaves é preservada, com uma exceção herdada dos objetos JavaScript: chaves que parecem inteiros não negativos são ordenadas numericamente e passam para a frente das demais. Comentários e espaços originais somem por definição, já que nenhum dos dois sobrevive à análise.

A visualização em árvore

Acima do texto formatado há uma árvore que pode ser recolhida. Ela serve para outra tarefa: entender o formato de uma resposta desconhecida, onde está o campo que interessa e o quanto ele está aninhado, sem rolar milhares de linhas indentadas. Recolha os arrays que não importam e a estrutura cabe numa tela.

O botão de copiar sempre entrega o texto formatado, então explorar pela árvore nunca muda o que você cola de volta no editor.

De onde veio o JSON e o que ele consegue guardar

O JSON foi especificado por Douglas Crockford no início dos anos 2000 como um subconjunto da sintaxe de objetos literais do JavaScript, a partir da observação de que os navegadores já sabiam interpretá-la e de que o XML era mais pesado do que a maioria das APIs web precisava. Ele foi padronizado como RFC 4627 e depois substituído pela RFC 8259 e pela ECMA-404, e o fato de a gramática caber em uma página explica boa parte de por que ele se impôs.

O modelo de dados é propositalmente pequeno: objetos, arrays, strings, números, booleanos e null. É só isso. Não há tipo de data, não há tipo binário, não há distinção entre inteiro e ponto flutuante, não há comentários e não há como expressar uma referência de uma parte do documento para outra.

Tudo o que é incômodo no JSON decorre dessa lista. Datas precisam ser uma convenção em vez de um tipo, dados binários precisam ser codificados como texto, inteiros grandes forçam um formato cujos números normalmente são interpretados como doubles, e arquivos de configuração - que pedem comentários - acabam tendo que usar um dialeto ou outro formato por completo.

Datas, dinheiro e números grandes

Para datas, a convenção consolidada é ISO 8601 em UTC, como em 2026-03-14T09:30:00Z. Ela ordena lexicograficamente, não é ambígua e qualquer linguagem consegue interpretá-la. As alternativas dão dor de cabeça: um timestamp Unix perde a distinção entre segundos e milissegundos, e uma string localizada como 03/14/2026 é ambígua fora do país que a escreveu.

Dinheiro não deve ser um número JSON. Os parsers têm liberdade para usar ponto flutuante de dupla precisão, então os problemas do tipo 0.1 mais 0.2 chegam junto com o payload, e o comportamento de arredondamento varia de uma linguagem para outra. Unidades monetárias menores em inteiro - 1999 para £19,99 - com a moeda em um campo separado é a representação que sobrevive a todo consumidor.

Identificadores grandes têm o mesmo problema de forma ainda mais aguda. Qualquer valor acima de 2^53 perde precisão ao ser interpretado como double, o que abrange ids de banco de dados de 64 bits e identificadores do tipo snowflake, de modo que eles devem aparecer no payload como strings. Isso não é hipotético: é por isso que várias APIs grandes retornam tanto um campo id quanto um campo id_str.

Arquivos grandes demais para caber na memória

Um parser que monta o documento inteiro como objeto precisa de várias vezes o tamanho do arquivo em memória, então uma exportação de 500 MB pode esgotar um processo mesmo em uma máquina com gigabytes livres. Duas abordagens evitam isso.

A primeira é o JSON delimitado por quebras de linha, em que cada linha é um documento completo e o arquivo como um todo não é um JSON válido. Ele flui naturalmente em streaming, aceita append de forma barata e é o que a maioria dos pipelines de log e formatos de exportação em massa usa. A segunda é um parser de streaming - o ijson em Python, um leitor no estilo SAX em outras linguagens - que emite eventos enquanto percorre o arquivo e nunca materializa a árvore inteira.

Na linha de comando, o jq dá conta dos dois casos e vale a pena aprender por si só: jq '.items[] | {id, name}' big.json extrai uma projeção sem carregar o documento em um editor. Sua flag --stream cobre os casos em que até o modo padrão do jq usaria memória demais.

A superfície de segurança de um payload JSON

Interpretar JSON é seguro em qualquer linguagem moderna; os riscos estão no que acontece em seguida. O mais conhecido é a poluição de protótipo: em JavaScript, mesclar em um objeto um JSON controlado por um atacante, sem filtrar, pode definir __proto__ e mudar o comportamento de todos os objetos do processo. Utilitários de merge profundo já entregaram esse bug várias vezes, e a defesa é rejeitar essas chaves explicitamente ou usar um objeto com protótipo nulo.

Nunca avalie JSON. Usar eval para interpretá-lo foi uma prática real na era anterior ao JSON.parse, e isso executa o que quer que chegue. Qualquer código que hoje recorra a eval sobre dados é um achado de segurança, não uma preferência de estilo.

Vale conhecer dois casos menores. Servir um array JSON com um content type que o navegador vai executar foi a base dos antigos ataques de JSON hijacking, e é por isso que algumas APIs ainda prefixam as respostas com uma linha que quebra o laço. E chaves duplicadas são legais na gramática, mas tratadas de maneira diferente por parsers diferentes, o que já foi usado para passar por um validador um valor distinto daquele que a aplicação acaba lendo.

Os dialetos e quando usar um deles

O JSON5 acrescenta comentários, vírgulas finais, chaves sem aspas e strings com aspas simples. O JSONC é a variante menor que o Visual Studio Code usa nas suas configurações e no tsconfig.json - essencialmente JSON mais comentários. Nenhum dos dois é JSON, e nenhum deles será interpretado por uma biblioteca padrão sem um pacote dedicado.

A distinção que importa é o público. Um arquivo mantido por uma pessoa ganha muito com comentários, então JSON5, JSONC, YAML ou TOML são todos razoáveis ali. Já um payload que atravessa a rede deve ser JSON puro, porque a ponta receptora pode ser qualquer linguagem e qualquer versão de biblioteca, e um dialeto converte uma garantia de interoperabilidade em uma dependência.

Quando você cola um arquivo de configuração em um parser rigoroso e ele falha, normalmente isso significa que o arquivo é um dialeto, e não que está malformado. Remover os comentários para agradar o parser é uma edição que destrói a documentação de alguém, então faça isso em uma cópia.