Formatar e validar JSON

De onde vem o JSON bagunçado

A maior parte do JSON que você encontra na prática foi escrita por um programa para outro programa, então chega numa única linha comprida: uma resposta de API copiada da aba de rede do navegador, o payload de um webhook num arquivo de log, um valor de configuração guardado numa coluna do banco de dados. Ler uma linha única de 4.000 caracteres para achar um campo aninhado é lento e propenso a erros. Embelezar o JSON coloca cada chave numa linha própria e recua cada nível, então a estrutura fica visível num relance.

O inverso é igualmente comum. Antes de colar JSON numa variável de ambiente, numa query string, numa fixture de teste ou numa mensagem de chat, muitas vezes você quer o texto o mais compacto possível. Minificar remove todos os espaços e quebras de linha que estão fora dos valores de string; um arquivo de configuração típico com recuo encolhe de 20 a 40 por cento, dependendo de quão profundo é o aninhamento.

O que o formatador faz com os seus dados

A entrada é analisada com o parser JSON nativo do navegador e escrita de volta com o recuo escolhido: 2 espaços, 4 espaços ou tab. Minificar usa o mesmo caminho, sem recuo nenhum. Como o documento é reconstruído a partir do valor analisado, e não editado como texto, alguns detalhes podem mudar, e vale saber quais:

• A notação dos números é normalizada. 1.0 vira 1, 1e3 vira 1000 e -0 vira 0. O valor é o mesmo, a grafia não.
• Inteiros muito grandes perdem precisão. O JavaScript guarda números como floats de 64 bits, que só são exatos até 9.007.199.254.740.991. Um ID de 19 dígitos como 12345678901234567890 volta como 12345678901234567000. Se os seus dados têm IDs no estilo Snowflake, bigints de banco de dados ou valores de pagamento em centavos nessa escala, compare a saída antes de usá-la.
• Escapes Unicode são decodificados. "caf\u00e9" é escrito de volta como "café". Os dois são JSON válido e representam a mesma string.
• Chaves duplicadas se fundem. Se um objeto contém a mesma chave duas vezes, só o último valor sobrevive. O padrão JSON deixa duplicatas indefinidas, e a maioria dos parsers se comporta assim.
• Chaves com cara de número inteiro vão para o início. Chaves que parecem números inteiros não negativos, como "2" ou "10", ficam primeiro, em ordem crescente, antes de todas as outras chaves. Isso é uma regra dos objetos JavaScript, não do JSON. Chaves de texto comuns mantêm a ordem original.

Nada disso importa em payloads típicos de API, mas importa se você vai fazer commit de um arquivo formatado e quer um diff mínimo.

Lendo a posição do erro

Quando a análise falha, a ferramenta roda um pequeno scanner próprio para encontrar o primeiro caractere que não pode continuar um documento válido, e informa essa posição como linha e coluna.

O ponto informado é onde o parser desistiu, o que nem sempre é onde o erro foi cometido:

• Uma vírgula sobrando em [1, 2, ] é apontada no colchete de fechamento, porque ali se esperava um valor.
• Uma vírgula faltando entre duas propriedades é apontada no início da segunda chave.
• Uma chave ou um colchete de fechamento faltando é apontado bem no fim da entrada, às vezes centenas de linhas abaixo do problema real. Procure o último objeto ou array que foi aberto.
• Uma string sem a aspa de fechamento é apontada no fim da sua linha, porque uma quebra de linha literal não é permitida dentro de uma string JSON. A mesma posição aparece para texto de várias linhas colado num valor; as quebras de linha ali precisam ser escritas como \n.

Se a entrada não for JSON de verdade, mas um literal de objeto JavaScript, YAML ou um dict do Python impresso com aspas simples, o erro vai aparecer na primeira ou na segunda linha. Esses formatos são parecidos, mas não intercambiáveis.

Escolhendo o recuo

• 2 espaços é o padrão na maioria das ferramentas JavaScript, nos arquivos package.json e em muitos guias de estilo. Evita que dados muito aninhados escapem pela borda direita da tela.
• 4 espaços corresponde ao que o json.dumps(indent=4) do Python gera e fica mais fácil de ler em documentos rasos.
• Tab deixa cada leitor escolher a largura visual no próprio editor e gera arquivos um pouco menores que com 4 espaços.

Para arquivos que ficam num repositório, siga o que o projeto já usa; misturar estilos deixa todo diff poluído.

Próximos passos com os dados formatados

Depois que a estrutura fica legível, outras tarefas ficam mais fáceis. Para espalhar um array de registros numa planilha, converta-o com o JSON para CSV. Para ver exatamente o que mudou entre duas versões de um payload, formate as duas com o mesmo recuo e compare-as no comparador de texto; com formatação idêntica, o diff mostra só as mudanças reais. Tudo acontece na página, então tokens e dados pessoais de um payload ficam no seu dispositivo.