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, et signale donc 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 ne signale aucun changement : mêmes clés, mêmes valeurs, seuls l'ordre des clés et le formatage diffèrent.

Ce que rapporte un diff structurel

Un diff JSON utile classe chaque différence par nature au lieu d'afficher du texte 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 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). Un changement de type pèse souvent plus lourd qu'un changement de valeur, car il peut casser des consommateurs qui supposaient une forme fixe.

Où les équipes utilisent le diff JSON

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, un diff structurel de chaque branche contre l'ancêtre commun montre quelles clés sont en conflit et lesquelles ont seulement 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 ont un nom : "role" dans le document A correspond toujours à "role" dans le document B. Les tableaux n'ont que des positions, donc un outil de diff doit décider si un élément à un autre index a été « déplacé » ou « modifié ». Insérez un élément en tête de liste et tous les index suivants se décalent de un. Un diff naïf index par index rapporte alors tout le reste du tableau comme changé, alors que vous n'avez ajouté qu'un élément. Les meilleurs outils apparient les éléments avec une heuristique (souvent un champ id stable, si les éléments en ont un) pour détecter insertions, suppressions et réordonnancements au lieu de traiter chaque index décalé comme un changement.