Comment comparer deux fichiers JSON et trouver ce qui a changé

La façon la plus rapide de comparer deux fichiers JSON est de coller les deux dans un outil de diff côte à côte, de les mettre dans le même format et de lire les lignes qu'il met en évidence. La partie difficile n'est généralement pas la comparaison. C'est le bruit : des clés réordonnées, une indentation différente et des virgules finales perdues peuvent faire paraître deux fichiers presque identiques comme s'ils ne partagent rien en commun.

Ce guide explique comment obtenir un diff propre et fiable. Nous verrons pourquoi les fichiers JSON divergent sur le papier tout en restant identiques dans leur signification, les quelques méthodes qui méritent d'être connues, et un exemple concret que vous pouvez suivre. Si vous voulez juste l'outil, notre page de comparaison JSON fait tout cela dans le navigateur.

Pourquoi les fichiers JSON sont trompeusement difficiles à comparer

JSON a une grammaire petite et stricte (voir la spécification sur json.org), mais elle laisse beaucoup de liberté aux auteurs dans la façon dont ils disposent le texte. Deux fichiers peuvent décrire exactement le même objet et différer néanmoins octet par octet. Un diff de texte brut ne sait rien de tout cela, il le signale donc fidèlement.

Voici ce qu'il faut intérioriser avant de commencer : les clés d'objet en JSON n'ont pas d'ordre. La spécification (RFC 8259) définit un objet comme un ensemble non ordonné de paires nom/valeur. Donc {"name":"Ada","id":7} et {"id":7,"name":"Ada"} sont égaux, même si un diff de lignes les colorera en rouge et en vert.

Ressemble à un changement, ne l'est généralement pas

Ce que vous voyez dans le diff	Est-ce un vrai changement ?	Que faire
Clés dans un ordre différent	Non, les objets sont non ordonnés	Trier les clés des deux côtés
Indentation 2 espaces vs 4 espaces	Non	Formater les deux côtés de la même façon
Minifié vs pretty-printed	Non	Formater les deux côtés
Saut de ligne en fin de fichier	Non	Ignorer, ou supprimer les espaces blancs
Une valeur est passée de "7" à 7	Oui, chaîne vs nombre	Examiner, c'est réel
Éléments d'un tableau dans un ordre différent	Peut-être, les tableaux sont ordonnés	Décider si l'ordre importe ici

Cette dernière ligne surprend les gens. Les tableaux conservent leur ordre, les objets non. Donc [1, 2, 3] et [3, 2, 1] sont genuinement différents, mais les clés à l'intérieur d'un objet peuvent se mélanger librement. Si vous voulez les détails techniques sur la façon dont JavaScript analyse tout cela, MDN dispose d'une solide référence sur l'objet JSON.

Quatre façons de comparer JSON et quand utiliser chacune

Il n'existe pas de méthode unique et meilleure. Tout dépend de l'emplacement des fichiers et de ce que vous cherchez à découvrir. Voici comment les options courantes se comparent.

Méthode	Idéal pour	Effort	Comprend le JSON ?
Examen visuel	Petits fichiers, un ou deux champs	Faible	Non, vous êtes le parser
Outil diff en ligne	Vérifications rapides, coller depuis n'importe où	Faible	Avec format + tri des clés, oui
Ligne de commande (jq, diff)	Fichiers sur disque, scripting, grands fichiers	Moyen	Oui, quand on trie d'abord
IDE ou git diff	Fichiers déjà dans un dépôt	Faible si commité	Basé sur les lignes par défaut

Pour la plupart des gens, un outil de navigateur l'emporte en vitesse car il n'y a rien à installer et vous pouvez coller un extrait directement depuis un log ou un appel API. L'inconvénient est le bruit de formatage, que nous allons gérer ensuite. Si vous vivez dans le terminal, jq est l'outil à apprendre, et nous montrerons l'unique option qui compte.

La comparaison propre la plus rapide, étape par étape

Voici la routine que j'utilise quand quelqu'un me donne deux fichiers de configuration et demande « qu'est-ce qui est différent ? » Cela prend environ quinze secondes.

1. Ouvrez l'outil de comparaison JSON.
2. Collez l'original à gauche et la nouvelle version à droite.
3. Cliquez sur Formater des deux côtés pour qu'ils partagent la même indentation.
4. Activez trier les clés (canonicaliser) pour que les clés réordonnées cessent d'apparaître comme des changements.
5. Lisez le résultat. Le vert est ajouté, le rouge est supprimé, et une valeur modifiée apparaît comme un de chaque.

Les étapes trois et quatre sont toute l'astuce. Une fois que les deux fichiers sont formatés de manière identique et que leurs clés sont triées, la seule chose restant à mettre en évidence est ce qui a réellement changé. Notre moteur de diff est construit sur le diff-match-patch de Google, qui compare ligne par ligne d'abord pour rester rapide même sur de longs fichiers.

Un exemple concret

Supposons que vous examinez une modification d'un enregistrement utilisateur. Voici l'avant :

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

Et voici l'après, tel qu'un collègue vous l'a remis :

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

Mettez-les dans un diff de lignes brut et il semble que presque chaque ligne a bougé, car les clés sont dans un ordre différent. Formatez et triez les deux, et la vraie histoire est courte :

Ce qui a réellement changé

Champ	Avant	Après	Changement
role	editor	admin	Modifié
seats	3	5	Modifié
team	—	platform	Ajouté
name	Ada Lovelace	Ada Lovelace	Aucun changement
active	true	true	Aucun changement (juste déplacé)

Trois vraies modifications : un changement de rôle, un nombre de sièges et un nouveau champ d'équipe. Le réordonnancement était du bruit. Cette promotion de editor à admin est le genre de chose que vous voulez repérer lors d'une revue, et il est facile de la manquer quand elle est noyée sous vingt lignes de faux positifs.

Éliminer le bruit de formatage en ligne de commande

Si vos fichiers sont déjà sur disque, la même idée de « formater et trier » fonctionne avec deux courtes commandes. L'option -S indique à jq de trier les clés d'objet ; les faire passer par cette commande normalise les deux fichiers pour qu'un diff simple soit honnête :

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

Maintenant diff ne signale que les valeurs qui ont vraiment changé, car les deux fichiers ont la même indentation et le même ordre de clés. C'est l'équivalent en terminal de cliquer sur Formater et trier les clés dans le navigateur.

Diff de texte vs diff structurel

Tout ce qui précède est un diff de texte : rapide, visuel et parfait pour qu'une personne lise un changement. Un diff structurel va plus loin et décrit le changement sous forme de données. La norme pour cela est JSON Patch, définie dans RFC 6902, qui exprime les modifications comme des opérations telles que replace et add à un chemin donné. Vous voulez un diff structurel quand un programme doit appliquer le changement, pas seulement une personne qui l'examine visuellement. Pour la revue quotidienne, un diff de texte avec des clés triées est amplement suffisant.

Pièges courants à surveiller

Piège	Pourquoi ça pose problème	Correction
Précision des nombres	Les entiers au-dessus de 2^53 − 1 perdent de la précision en JavaScript	Comparer les grands IDs comme des chaînes ; voir MAX_SAFE_INTEGER
Échappements Unicode	"café" et "café" sont la même chaîne, des octets différents	Formater les deux côtés, ce qui normalise l'encodage
Clés dupliquées	La plupart des parsers gardent silencieusement le dernier	Valider le JSON avant de faire confiance au diff
Virgules finales	Non valide en JSON ; un fichier peut ne pas se parser	Corriger la syntaxe d'abord, le validateur le signalera
Chaîne vs nombre	"5" et 5 semblent pareils mais sont de types différents	C'est un vrai changement, ne le négligez pas

Outils associés

JSON est rarement le seul format avec lequel vous travaillez. Si vous comparez des configurations entre environnements, comparer YAML applique la même idée à YAML. Examiner les changements entre deux appels API est ce pour quoi l'outil de diff de réponses API est conçu, et les mises à jour de dépendances sont plus faciles à lire sur la page de diff de package.json.