Confrontando due documenti JSON con un diff testuale normale (come per il codice), il risultato è spesso fuorviante: gli stessi dati possono essere scritti con un ordine di chiavi diverso, indentazione diversa o un numero diverso di spazi — e il diff testuale mostrerà una "differenza" dove i dati in realtà sono identici.
Confronto strutturale
Un JSON Diff strutturale analizza entrambi i documenti come un albero di valori e confronta i dati veri e propri: se un campo esiste, quale valore contiene, se il tipo corrisponde. L'ordine delle chiavi di un oggetto, gli spazi in eccesso o lo stile di indentazione non vengono considerati — non fanno parte dei dati stessi.
Cosa mostra il diff
Un risultato tipico di confronto strutturale evidenzia tre tipi di modifiche: campi aggiunti nel secondo documento, campi rimossi dal primo, e campi presenti in entrambi ma con valori diversi. Per gli array il confronto è più complesso — bisogna decidere se confrontare gli elementi per posizione o cercare di abbinare oggetti simili.
A cosa serve
- Confrontare una risposta API prima e dopo una modifica sul backend per vedere le differenze reali nei dati.
- Verificare che una modifica in un file di configurazione non abbia toccato nulla di superfluo.
- Individuare una regressione nei test dove il JSON atteso e quello effettivo differiscono.
Diff degli open data della Pubblica Amministrazione
Portali come dati.gov.it pubblicano dataset versionati in JSON, e confrontare due versioni dello stesso schema — ad esempio l'elenco delle scuole o degli enti locali — con un diff strutturale è il modo pratico per capire cosa è realmente cambiato tra un aggiornamento e l'altro, senza dover scorrere manualmente file che possono contenere migliaia di record. In questi contesti un diff testuale sarebbe quasi inutile, perché l'ordine dei record e la formattazione variano da un export all'altro anche quando i dati sostanziali restano identici.
Confrontare gli array: per posizione o per chiave
L'approccio più semplice è confrontare gli elementi dell'array indice per indice, ma se al centro dell'array viene inserito un nuovo elemento, tutte le posizioni successive si "spostano" e il diff mostrerà una modifica in ogni elemento dopo il punto di inserimento, anche se in realtà ne è cambiato solo uno. Gli strumenti più sofisticati cercano invece di abbinare gli elementi in base a un campo univoco (ad esempio id), per mostrare esattamente l'inserimento o la rimozione, e non una cascata di modifiche fittizie.