Come confrontare due file JSON e trovare le differenze

Il modo più rapido per confrontare due file JSON è incollarli entrambi in uno strumento di diff affiancato, formattarli allo stesso modo e leggere le righe evidenziate. La parte difficile di solito non è il confronto. È il rumore: chiavi riordinate, rientri diversi e virgole finali sparse possono far sembrare che due file quasi identici non abbiano nulla in comune.

Questa guida spiega come ottenere un diff pulito e affidabile. Vedremo perché i file JSON sembrano divergere sulla carta rimanendo identici nel significato, i pochi metodi che vale la pena conoscere e un esempio pratico da seguire. Se si vuole solo lo strumento, la nostra pagina di confronto JSON fa tutto questo nel browser.

Perché i file JSON sono ingannevolmente difficili da confrontare

JSON ha una grammatica piccola e rigorosa (vedi la specifica su json.org), ma lascia molta libertà nella disposizione del testo. Due file possono descrivere lo stesso oggetto e differire byte per byte. Un semplice diff di testo non sa nulla di tutto ciò, quindi lo segnala tutto diligentemente.

Ecco la cosa fondamentale da interiorizzare prima di iniziare: le chiavi degli oggetti in JSON non hanno ordine. La specifica (RFC 8259) definisce un oggetto come un insieme non ordinato di coppie nome/valore. Quindi {"name":"Ada","id":7} e {"id":7,"name":"Ada"} sono uguali, anche se un diff per righe li colorerà di rosso e verde.

Sembra una modifica, di solito non lo è

Cosa si vede nel diff	È una vera modifica?	Cosa fare
Chiavi in ordine diverso	No, gli oggetti non sono ordinati	Ordinare le chiavi su entrambi i lati
Rientro a 2 spazi vs 4 spazi	No	Formattare entrambi i lati allo stesso modo
Minimizzato vs formattato	No	Formattare entrambi i lati
Riga vuota finale alla fine del file	No	Ignorare o rimuovere gli spazi bianchi
Un valore è cambiato da "7" a 7	Sì, stringa vs numero	Indagare, è reale
Elementi dell'array in ordine diverso	Forse, gli array sono ordinati	Decidere se l'ordine è rilevante qui

L'ultima riga sorprende molti. Gli array mantengono il loro ordine, gli oggetti no. Quindi [1, 2, 3] e [3, 2, 1] sono genuinamente diversi, ma le chiavi all'interno di un oggetto possono essere mescolate liberamente. Per i dettagli su come JavaScript analizza tutto questo, MDN ha un ottimo riferimento sull'oggetto JSON.

Quattro modi per confrontare JSON e quando usarne ciascuno

Non esiste un metodo unico migliore. Dipende da dove si trovano i file e cosa si vuole scoprire. Ecco come si confrontano le opzioni più comuni.

Metodo	Ideale per	Sforzo	Capisce JSON?
Esame visivo	File piccoli, uno o due campi	Basso	No, sei tu il parser
Strumento diff online	Controlli rapidi, incollare da qualsiasi fonte	Basso	Con formato + ordinamento chiavi, sì
Riga di comando (jq, diff)	File su disco, scripting, file di grandi dimensioni	Medio	Sì, ordinando prima
IDE o git diff	File già in un repository	Basso se committati	Basato sulle righe per impostazione predefinita

Per la maggior parte delle persone uno strumento browser vince in velocità perché non c'è nulla da installare e si può incollare uno snippet direttamente da un log o da una chiamata API. Il problema è il rumore di formattazione, di cui ci occuperemo subito dopo. Chi lavora molto nel terminale dovrebbe imparare jq, e mostreremo il flag che conta.

Il confronto pulito più rapido, passo dopo passo

Questa è la procedura che uso quando qualcuno mi dà due file di configurazione e chiede "cosa è diverso?" Richiede circa quindici secondi.

1. Aprire lo strumento di confronto JSON.
2. Incollare l'originale a sinistra, la nuova versione a destra.
3. Fare clic su Formatta su entrambi i lati in modo che condividano lo stesso rientro.
4. Attivare Ordina chiavi (canonicalizza) in modo che le chiavi riordinate smettano di apparire come modifiche.
5. Leggere il risultato. Il verde indica aggiunto, il rosso indica rimosso, e un valore modificato appare come uno di ciascuno.

I passi tre e quattro sono il trucco vero. Una volta che entrambi i file sono formattati in modo identico e le loro chiavi sono ordinate, l'unica cosa rimasta da evidenziare è ciò che è effettivamente cambiato. Il nostro motore di diff è costruito su diff-match-patch di Google, che confronta prima riga per riga così rimane veloce anche su file lunghi.

Un esempio pratico

Supponiamo che si stia esaminando una modifica a un record utente. Ecco com'era prima:

{
  "name": "Ada Lovelace",
  "role": "editor",
  "active": true,
  "seats": 3
}

E qui è il dopo, come lo ha consegnato un collega:

{
  "active": true,
  "name": "Ada Lovelace",
  "role": "admin",
  "seats": 5,
  "team": "platform"
}

Se si inseriscono in un semplice diff per righe sembra che quasi ogni riga si sia spostata, perché le chiavi sono in ordine diverso. Formattando e ordinando entrambi, la storia vera è breve:

Cosa è cambiato davvero

Campo	Prima	Dopo	Modifica
role	editor	admin	Modificato
seats	3	5	Modificato
team	—	platform	Aggiunto
name	Ada Lovelace	Ada Lovelace	Nessuna modifica
active	true	true	Nessuna modifica (solo spostato)

Tre vere modifiche: un cambio di ruolo, un conteggio dei posti e un nuovo campo team. Il riordinamento era rumore. Quella promozione da editor ad admin è esattamente il tipo di cosa che si vuole individuare in revisione, ed è facile perderla quando è sepolta sotto venti righe di falsi positivi.

Eliminare il rumore di formattazione dalla riga di comando

Se i file sono già su disco, la stessa idea di "formatta e ordina" funziona con due brevi comandi. Il flag -S dice a jq di ordinare le chiavi degli oggetti; inviare tramite pipe normalizza entrambi i file in modo che un semplice diff sia onesto:

jq -S . old.json > old.sorted.json
jq -S . new.json > new.sorted.json
diff old.sorted.json new.sorted.json

Ora diff riporta solo i valori che sono veramente cambiati, perché entrambi i file hanno lo stesso rientro e lo stesso ordine delle chiavi. Questo è l'equivalente nel terminale di fare clic su Formatta e ordina chiavi nel browser.

Diff di testo vs diff strutturale

Tutto quanto sopra è un diff di testo: veloce, visivo e perfetto per una persona che legge una modifica. Un diff strutturale va oltre e descrive la modifica come dati. Lo standard per questo è JSON Patch, definito in RFC 6902, che esprime le modifiche come operazioni come replace e add a un percorso dato. Si vuole un diff strutturale quando un programma deve applicare la modifica, non solo una persona che la esamina visivamente. Per la revisione quotidiana, un diff di testo con chiavi ordinate è più che sufficiente.

Insidie comuni da tenere d'occhio

Insidia	Perché colpisce	Soluzione
Precisione dei numeri	Gli interi sopra 2^53 − 1 perdono precisione in JavaScript	Confrontare grandi ID come stringhe; vedi MAX_SAFE_INTEGER
Escape Unicode	"café" e "café" sono la stessa stringa, byte diversi	Formattare entrambi i lati, il che normalizza la codifica
Chiavi duplicate	La maggior parte dei parser mantiene silenziosamente l'ultima	Validare il JSON prima di fidarsi del diff
Virgole finali	Non JSON valido; un file potrebbe non essere nemmeno parsabile	Correggere prima la sintassi, il validatore lo segnalerà
Stringa vs numero	"5" e 5 sembrano simili ma sono tipi diversi	È una vera modifica, non ignorarla

Strumenti correlati

JSON è raramente l'unico formato con cui si ha a che fare. Se si confrontano configurazioni tra ambienti, il confronto YAML applica la stessa idea a YAML. Esaminare le modifiche tra due chiamate API è esattamente ciò per cui è costruito il diff delle risposte API, e gli aggiornamenti delle dipendenze sono più facili da leggere sulla pagina package.json diff.