Comparador JSON

O que é um comparador JSON?#

Um comparador JSON (diff) compara dois documentos JSON e diz-lhe exatamente o que mudou entre eles — que campos apareceram, que desapareceram, e quais mantiveram o mesmo caminho mas assumiram um valor diferente. É o equivalente estrutural de um diff de texto, mas em vez de comparar linhas percorre a árvore de objetos e arrays, pelo que um valor que passe de 1 para 2 surge como uma edição precisa num caminho específico, não como um bloco de texto reescrito.

Isto importa sempre que o JSON é o formato de transporte de algo que evolui: respostas de API entre deploys, arquivos de configuração entre revisões, fixtures de testes, dados exportados entre dias. Olhar para dois blocos embelezados lado a lado só funciona para documentos minúsculos; no momento em que o aninhamento se aprofunda, é preciso enumerar as diferenças.

O senão é que o diff JSON é sensível à ordem dos arrays. Dois arrays só são iguais se os seus elementos corresponderem posição a posição, porque é assim que o próprio JSON define igualdade. Por isso [a, b] e [b, a] são diferentes, e o diff reportá-lo-á — útil quando a ordem é significativa (uma sequência de passos), surpreendente quando não é (um conjunto disfarçado de array).

Como usar#

1. Cole o documento original no painel Esquerda (original) e o revisto no painel Direita (alterado).
2. A comparação decorre em tempo real à medida que escreve. Também pode clicar em Comparar para forçar uma atualização.
3. A área de saída lista cada diferença na sua própria linha:
   • Adicionado — o caminho existe apenas à direita; a linha mostra o novo valor.
   • Removido — o caminho existe apenas à esquerda; a linha mostra o valor antigo.
   • Alterado — o caminho existe em ambos os lados mas com valor diferente; a linha mostra antigo → novo. Cada linha é prefixada com um caminho ao estilo JSONPath, como $.version ou $.tags[2], para que o consiga localizar em qualquer dos documentos.
4. Se ambos os documentos forem profundamente iguais, a linha de estado diz-o explicitamente — “sem diferenças” — em vez de deixar um painel vazio para interpretar.
5. Exemplo carrega um par antes/depois realista; Limpar repõe ambos os painéis e o resultado.

Principais funcionalidades#

• Estrutural, não textual. Compara a árvore de valores analisada, pelo que re-indentar, reordenar chaves de objeto ou alterar espaços em branco nunca produz uma falsa diferença.
• Caminhos precisos. Cada alteração transporta a sua localização em notação JSONPath — $ para a raiz, .key para campos de objeto, [i] para índices de array — pelo que pode saltar diretamente para o sítio certo.
• Três tipos de alteração. Adicionado, removido e alterado são reportados separadamente e com código de cor, pelo que as adições se destacam das remoções e edições num relance.
• Relatório de erros por lado. Se uma entrada não for JSON válido, a linha de estado indica qual o lado que falhou (A entrada da esquerda não é um JSON válido.) em vez de falhar de forma opaca.
• Comparação em tempo real. O diff atualiza-se à medida que edita qualquer dos painéis, pelo que iterar sobre uma fixture ou resposta é imediato.

Exemplo prático#

Carregue em Exemplo e os dois painéis preenchem-se com um pequeno documento de configuração antes e depois de uma revisão:

{
  "name": "ArpGate",
  "version": 1,
  "tags": ["json", "encoding"],
  "features": { "static": true, "backend": null }
}

à esquerda, contra:

{
  "name": "ArpGate",
  "version": 2,
  "tags": ["json", "encoding", "crypto"],
  "features": { "static": true, "backend": false, "offline": true }
}

à direita. O diff enumera exatamente o que se moveu:

changed  $.version           1 → 2
added    $.tags[2]           "crypto"
changed  $.features.backend  null → false
added    $.features.offline  true

Repare no que não aparece: $.name (inalterado), $.tags[0] e $.tags[1] (inalterados) e $.features.static (inalterado). Ramos iguais não produzem saída, pelo que um diff de quatro linhas é a história completa, apesar de ambos os documentos terem vários campos. Se depois definir ambos os painéis com o mesmo documento, a linha de estado muda para “sem diferenças — as entradas são idênticas”.

FAQ#

Porque é que um array reordenado aparece como totalmente alterado?#

Os arrays JSON são ordenados, e a igualdade é posicional. [1, 2] e [2, 1] diferem no índice 0 e no índice 1, pelo que o diff reporta duas alterações. Isso está correto para sequências em que a ordem é significativa. Se o seu array representar um conjunto, ordene-o (ou normalize-o) em ambos os documentos antes de comparar — caso contrário, movimentos parecerão edições.

Deteta quando uma chave de objeto é renomeada?#

Reporta-o como uma remoção mais uma adição, porque o JSON não tem forma de expressar “esta chave tornou-se aquela chave”. Renomear enabled para active surge como removed $.enabled e added $.active — duas linhas, não um “rename”. Essa é a representação honesta do que mudou nos dados.

Como é que se parece uma alteração de tipo?#

É reportada como uma única linha changed. Se um valor passa da string "36" para o número 36, o diff mostra "36" → 36 nesse caminho — as serializações diferentes tornam a mudança de tipo visível. O mesmo se aplica a null que passa a false, ou a um número que se torna um objeto.

Consegue dizer-me que campos estão inalterados?#

Não, e propositadamente. Listar todos os campos inalterados afogaria as alterações reais em ruído em qualquer documento real. O diff mostra apenas os deltas; ramos iguais mantêm-se em silêncio. Se precisar da forma completa de um documento, renderize-o com o visualizador de árvore.