Comparar dois documentos JSON com um diff de texto comum (como o usado para código) costuma dar um resultado enganoso: os mesmos dados podem ser escritos com ordem de chaves diferente, indentação diferente ou uma quantidade diferente de espaços — e o diff de texto vai mostrar uma "diferença" onde os dados são, na verdade, idênticos.
Comparação estrutural
Um JSON Diff estrutural analisa os dois documentos como uma árvore de valores e compara os próprios dados: se um campo existe, qual valor ele contém, se o tipo corresponde. A ordem das chaves de um objeto, espaços extras ou o estilo de indentação não são levados em conta — eles não fazem parte dos dados em si.
O que o diff mostra
Um resultado típico de comparação estrutural destaca três tipos de mudanças: campos adicionados no segundo documento, campos removidos do primeiro, e campos presentes em ambos mas com valores diferentes. Para arrays a comparação é mais complexa — é preciso decidir se compara os elementos por posição ou tenta parear objetos semelhantes.
Para que serve
- Comparar a resposta de uma API antes e depois de uma mudança no backend para ver as diferenças reais nos dados.
- Verificar que uma mudança num arquivo de configuração não afetou nada além do previsto.
- Encontrar uma regressão em testes onde o JSON esperado e o real diferem.
pt-BR contra pt-PT: o diff que revela vocabulário, não bugs
Times que mantêm um produto para Brasil e Portugal ao mesmo tempo costumam ter dois arquivos de tradução, pt-BR.json e pt-PT.json, com chaves idênticas mas valores que divergem por vocabulário — "ônibus" versus "autocarro", "celular" versus "telemóvel", "fila" versus "bicha". Um diff estrutural entre os dois não deveria ser lido como "bug de tradução": ele existe justamente para confirmar que as duas variantes têm a mesma cobertura de chaves, mesmo com conteúdo diferente, e para pegar o caso real de erro — uma chave presente em um arquivo e esquecida no outro.
Comparação de arrays: por posição ou por chave
A abordagem mais simples é comparar os elementos de um array índice a índice, mas se um novo elemento for inserido no meio do array, todas as posições seguintes "deslocam" e o diff mostra uma mudança em cada elemento após o ponto de inserção, embora apenas um tenha realmente mudado. Ferramentas mais sofisticadas tentam parear os elementos por um campo único (como id), para mostrar exatamente a inserção ou remoção, em vez de uma cascata de mudanças falsas.