Formatar JSON

Formatar aqui significa ler o documento inteiro e escrevê-lo de novo. A alternativa barata — ir enfiando quebras de linha e espaços onde aparece uma chave — funciona até o dia em que uma string contém uma chave, e aí ela destrói o documento de um jeito que continua parecendo JSON.

A consequência útil é que formatar também é uma verificação. Se saiu alguma coisa, o documento era válido; se não saiu, não era, e para isso existe a página de validação, que diz em que linha o parser trava. Um formatador que nunca falha é um formatador que não está lendo o que você entregou.

Dois espaços é o que o `JSON.stringify` escreve quando se pede indentação e o padrão de quase toda ferramenta do mundo JavaScript. Quatro vem do mundo Python e Java. A tabulação economiza bytes e deixa cada pessoa escolher a largura no editor dela.

Nenhuma das três muda o documento: para um parser, o espaço em branco entre elementos não existe. Isso só importa se o resultado for para um repositório, onde uma mistura de convenções produz diferenças em linhas que ninguém tocou — o motivo pelo qual convém fixar uma e deixar que a ferramenta fixe, não a pessoa.

Um objeto JSON não tem ordem definida, então dois serviços podem devolver os mesmos dados com as chaves em posições diferentes. Ordenar em ordem alfabética transforma uma comparação de texto em uma comparação útil, que é exatamente o que se precisa antes de um diff ou de um teste de contrato.

Um array é o contrário: a ordem dele faz parte do dado. Aqui ela nunca é mexida, e essa assimetria é deliberada. Uma ferramenta que também ordenasse arrays produziria documentos que comparam bem e significam outra coisa, que é a pior combinação possível.

O JSON escreve números como texto e o JavaScript os lê como ponto flutuante de precisão dupla. Inteiros acima de cerca de nove quatrilhões perdem dígitos: um identificador de 19 dígitos volta diferente, e como o resultado continua parecendo um número válido ninguém percebe.

Isso atinge qualquer processamento que passe por um parser de JavaScript, este incluído, e é avisado quando acontece. O gatilho de sempre são os identificadores tipo snowflake do Twitter e do Discord e algumas sequências de banco de dados. A solução está em quem os gera: esses valores devem viajar como string, e aí atravessam qualquer etapa sem mudar.

Não há comentários, não há vírgula sobrando no fim, não há aspas simples e não há chave sem aspas. Cada uma dessas coisas é um hábito trazido do JavaScript, e cada uma para o parser com uma mensagem que quase nunca aponta o lugar certo.

Quem precisa de comentário numa configuração tem três saídas: usar um formato que aceite — YAML, TOML, JSON5 —, colocar um campo `_comentario` que seja ignorado de propósito, ou remover os comentários antes de processar. A terceira é a mais comum e a mais frágil, porque uma barra dupla também aparece dentro de uma URL.

O resultado sai em UTF-8 como está, sem transformar os caracteres não ASCII em sequências de escape `\uXXXX`. As duas formas são JSON válido e significam a mesma coisa, mas a primeira se lê e a segunda não: um nome com cedilha escrito como `\u00e7` é correto e é ilegível.

Algumas bibliotecas escapam por padrão porque assumem que o transporte não é limpo, o que deixou de ser verdade faz tempo. Se os seus dados chegam com essas sequências, este formatador não as converte de volta — elas fazem parte do documento do jeito que você o recebeu, e mudá-las seria reescrever o dado e não a apresentação dele.

O JSON não proíbe repetir uma chave dentro do mesmo objeto, e cada implementação resolve isso do seu jeito. O parser do navegador, e portanto esta página, fica com a última ocorrência; outros ficam com a primeira, e alguns devolvem erro.

O resultado é que um documento com chave repetida pode significar coisas diferentes em dois sistemas que estão os dois certos. Se um valor «desaparece» entre dois serviços, procure uma chave duplicada antes de procurar um bug: formatar aqui deixa isso visível, porque a saída tem apenas uma delas.

O JSON tem seis tipos e nenhum deles é data. Um `NaN` e um `Infinity` também não existem: são literais do JavaScript, e escrevê-los num documento produz um arquivo que o próprio JavaScript recusa ao ler de volta.

Por isso as datas viajam como string, quase sempre em ISO 8601, e é responsabilidade das duas pontas combinar o formato. Onde alguém serializou um `NaN` sem perceber, o sintoma costuma ser um documento que a aplicação gera e não consegue reler — e o formatador aqui vai parar exatamente naquele ponto.

Ela resolve um problema de leitura: existe um documento na sua frente e não dá para ver a forma dele. É o que se precisa quando chega uma resposta de API em uma linha, quando um campo de log carrega JSON dentro ou quando alguém cola um bloco de configuração num chamado.

Ela não resolve o problema inverso. Para deixar tudo em uma linha existe a página de minificar, e para descobrir por que alguma coisa está recusando o documento existe a de validar, que dá a linha e a coluna. As três compartilham o motor e estão separadas porque são três momentos com três perguntas.

Um JSON minificado dentro de um arquivo versionado transforma qualquer mudança em uma linha alterada. O diff vira tudo ou nada, a revisão fica impossível e um conflito de merge atinge o documento inteiro em vez dos dois campos de que ele tratava.

A divisão que funciona é a óbvia: formatado no repositório, minificado na hora de servir. Entre os dois estados está exatamente o passo que um processo de build deveria dar sozinho, e nenhuma das duas formas é a correta em abstrato — elas são corretas cada uma no seu lugar.

Um payload JSON contém com frequência justamente o que não convém mover: cadastro de cliente, dados de pedido, um webhook com endereços dentro. Como aqui o documento passa por parse e é reescrito na própria página, não há compartilhamento conosco e portanto não somos operador desse conteúdo.

Isso se demonstra no painel de rede: enquanto você usa a ferramenta, nenhuma requisição sai levando o seu documento. É a razão pela qual esta ferramenta pode ser usada onde uma versão com servidor esbarraria numa política interna, e conferir custa um minuto.