Comment diff et comparer des documents JSON (sans perdre la tête)

Pourquoi un diff textuel vous induit en erreur sur le JSON

Un outil de diff textuel compare ligne par ligne. Si un sérialiseur JSON change l'ordre des clés, passe d'une indentation de 2 à 4 espaces, ou écrit 1.50 au lieu de 1.5, un diff textuel marque chaque ligne comme modifiée — alors que les données analysées sont identiques. Un diff structurel analyse d'abord les deux documents, puis compare les valeurs résultantes : il signale correctement zéro différence pour un objet réordonné mais égal.

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

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

Un diff par lignes sur cette paire montre tout comme réécrit. Un diff structurel signale correctement aucun changement — mêmes clés, mêmes valeurs, seul l'ordre des clés et le formatage diffèrent.

Ce qu'un diff structurel rapporte réellement

Un diff JSON utile catégorise chaque différence par nature plutôt que d'afficher du brut avant/après : ajouté — une clé présente dans le nouveau document mais pas dans l'ancien. supprimé — une clé présente dans l'ancien document mais absente du nouveau. modifié — une clé présente dans les deux, mais avec une valeur différente. type modifié — une valeur qui a changé de type de données (une chaîne devenue nombre, un objet devenu tableau), souvent un signal plus grave qu'un simple changement de valeur car il peut casser des consommateurs qui supposaient une forme fixe.

Là où le diff JSON est réellement utilisé

Tests de régression d'API : capturez une réponse connue comme bonne, puis comparez chaque nouvelle réponse à elle dans la CI. Un diff structurel signale les vrais changements de contrat (un champ renommé ou supprimé) tout en ignorant le bruit cosmétique comme l'ordre des clés ou les valeurs d'horodatage censées changer à chaque exécution.

Détection de dérive de configuration : comparez la configuration en direct d'un service déployé à la version versionnée dans le contrôle de source pour intercepter les modifications manuelles hors bande avant qu'elles provoquent un incident.

Pistes d'audit : stockez un résumé du diff à côté d'un instantané « avant » et « après » chaque modification d'un enregistrement, pour que les relecteurs voient exactement quels champs ont bougé au lieu de relire deux documents complets côte à côte.

Résolution de conflits de fusion : quand deux branches modifient une même configuration JSON partagée, un diff structurel de chaque branche contre l'ancêtre commun rend bien plus clair quelles clés spécifiques sont réellement en conflit, par opposition à celles qui ont simplement des changements sans rapport à proximité.

Pourquoi les tableaux sont le point dur du diff JSON

Les objets se comparent proprement parce que les clés sont nommées — "role" dans le document A correspond toujours à "role" dans le document B. Les tableaux n'ont pas de noms, seulement des positions, donc un outil de diff doit décider si un élément à un index différent est « déplacé » ou « différent ». Insérer un élément en tête de liste décale tous les index suivants de un — un diff naïf index par index rapporte tout le reste du tableau comme changé, alors qu'un seul élément a été ajouté. Les meilleurs outils de diff utilisent une heuristique d'appariement (souvent basée sur un champ id stable, s'il existe dans les éléments) pour détecter correctement insertions, suppressions et réordonnancements, au lieu de traiter chaque index décalé comme un changement.