Como comparar e fazer diff de documentos JSON (sem perder a cabeça)

Por que um diff de texto engana você no JSON

Uma ferramenta de diff de texto compara linha por linha. Se um serializador JSON muda a ordem das chaves, troca indentação de 2 por 4 espaços, ou escreve 1.50 em vez de 1.5, um diff de texto marca toda linha como alterada, embora os dados analisados sejam idênticos. Um diff estrutural analisa os dois documentos primeiro e depois compara os valores, então reporta zero diferenças para um objeto reordenado, porém igual.

// Version A
{"name": "Ada", "role": "admin"}

// Version B
{
  "role": "admin",
  "name": "Ada"
}

Um diff baseado em linhas nesse par mostra tudo como reescrito. Um diff estrutural não reporta nenhuma mudança: mesmas chaves, mesmos valores, só a ordem das chaves e a formatação mudam.

O que um diff estrutural reporta

Um diff de JSON útil classifica cada diferença por tipo em vez de mostrar texto bruto de antes/depois. added: uma chave presente no documento novo mas não no antigo. removed: uma chave presente no documento antigo mas ausente no novo. changed: uma chave presente em ambos com valor diferente. type-changed: um valor que trocou de tipo de dados (uma string virou número, um objeto virou array). Uma troca de tipo costuma pesar mais que uma troca de valor, porque pode quebrar consumidores que assumiam um formato fixo.

Onde os times usam diff de JSON

Testes de regressão de API: capture uma resposta sabidamente boa e depois compare cada nova resposta contra ela no CI. Um diff estrutural sinaliza mudanças reais de contrato (um campo renomeado ou removido) enquanto ignora ruído cosmético como ordem de chaves ou valores de timestamp que mudam a cada execução por natureza.

Detecção de desvio de configuração: compare a configuração em produção de um serviço implantado contra a versão versionada no controle de código para pegar alterações manuais fora do processo antes que causem um incidente.

Trilhas de auditoria: armazene um resumo do diff junto com um snapshot 'antes' e 'depois' sempre que um registro muda, para que revisores vejam exatamente quais campos mudaram, em vez de reler dois documentos completos lado a lado.

Resolução de conflitos de merge: quando dois branches modificam uma configuração JSON compartilhada, um diff estrutural de cada branch contra o ancestral comum mostra quais chaves conflitam e quais só têm mudanças não relacionadas por perto.

Por que arrays são a parte mais difícil do diff de JSON

Objetos são comparados de forma limpa porque as chaves têm nome: "role" no documento A sempre corresponde a "role" no documento B. Arrays só têm posição, então uma ferramenta de diff precisa decidir se um item em outro índice foi 'movido' ou 'alterado'. Insira um item no início de uma lista e todo índice seguinte se desloca em um. Um diff ingênuo índice a índice reporta então o resto do array como alterado, quando você só adicionou um item. Ferramentas melhores pareiam itens com uma heurística (muitas vezes um campo id estável, se os itens tiverem) para detectar inserções, remoções e reordenações em vez de tratar cada índice deslocado como mudança.