Canonicalisez d'abord avec le formateur JSON, puis comparez avec l'outil de diff texte.
Pourquoi le diff texte ment sur le JSON
JSON est un format de données, pas un format texte. Deux documents peuvent être sémantiquement identiques et pourtant totalement différents en texte : ordre des clés, indentation, espaces ou caractères échappés différents.
Un diff texte ligne par ligne met en évidence chacune de ces différences cosmétiques. La revue d'un changement de réponse API devient un mur de lignes rouges et vertes même quand le seul vrai changement était un champ.
Le diff texte répond à la question « quels caractères diffèrent ? » Le diff JSON répond à « quelles données ont changé ? » – et pour la configuration, les réponses API et les fixtures de test, c'est la question qui compte vraiment.
Quand le diff texte est le bon outil
- Vous révisez du JSON généré et voulez voir aussi les changements de formatage
- Vous suspectez des caractères invisibles, des différences d'encodage ou d'espaces
- Les fichiers sont petits et l'ordre des clés compte pour vos outils
- Vous faites un diff d'un extrait de journal ou d'un JSON intégré dans un fichier texte plus large
Quand le diff JSON sémantique est le bon outil
- Comparer des réponses API entre déploiements ou environnements
- Réviser des changements de configuration où l'ordre des clés n'a pas d'importance
- Vérifier si deux fichiers générés sont équivalents après l'exécution d'un formateur
- Écrire des tests qui doivent échouer sur de vrais changements de données, pas sur le formatage
Comparer le JSON sémantiquement, pas à pas
- Ouvrez le formateur JSON et collez le premier document.
- Formatez et minifiez le résultat pour normaliser l'ordre des clés et les espaces.
- Répétez pour le deuxième document.
- Ouvrez l'outil de diff texte et collez les deux versions normalisées.
- Examinez le diff – désormais chaque différence est une vraie différence de données.
Remarque: Normaliser l'ordre des clés avant le diff est l'astuce essentielle. Une fois que les deux côtés utilisent le même ordre de clés et les mêmes espaces, un diff texte devient un diff sémantique bon marché et précis.
Quand l'ordre lui-même est la donnée
Les tableaux JSON sont ordonnés – [1,2,3] et [3,2,1] sont des valeurs différentes. Un diff sémantique doit comparer les tableaux par position, ce qu'une approche naïve de tri des clés peut rater.
Pour les API et configurations, c'est le comportement correct. Si votre application traite les clés d'objet comme ordonnées (certains outils le font), la comparaison textuelle est la plus honnête.
Les normes comme JSON Patch et JSON Merge Patch formalisent la représentation des changements : JSON Patch est une liste d'opérations ajouter/supprimer/remplacer, JSON Merge Patch est un document partiel. Comprendre lequel votre API attend élimine toute une classe de confusions de diff.
Diff texte vs diff JSON en un coup d'œil
| Question | Diff texte | Diff JSON sémantique |
|---|---|---|
| Les octets ont-ils changé ? | Oui – montre chaque différence d'octets | Seulement si les données ont changé |
| Les données ont-elles changé ? | Bruyant, dépend du formatage | Oui – précis |
| Changements d'ordre des clés | Montrés comme un changement | Ignorés (les objets ne sont pas ordonnés) |
| Déplacements d'éléments de tableau | Montrés comme un changement | Montrés – les tableaux sont ordonnés |
| Espaces / indentation | Montrés | Ignorés |
FAQ
Q.Pourquoi mon diff JSON montre des changements que je n'ai pas faits ?
A.Presque toujours parce que les deux fichiers diffèrent par l'ordre des clés, l'indentation ou les espaces de fin. Normalisez les deux côtés avec un formateur et re-faites le diff pour voir le vrai changement de données.
Q.JSON tient-il compte de l'ordre des clés ?
A.Selon RFC 8259, les objets JSON sont des collections non ordonnées de paires nom/valeur. La plupart des analyseurs et API les traitent ainsi, donc la comparaison sémantique ignore l'ordre des clés – sauf si vos outils s'appuient explicitement dessus.
Q.Les tableaux sont-ils comparés par position ?
A.Oui. Les tableaux JSON sont ordonnés, donc [1,2] et [2,1] sont différents. Un bon outil de diff les compare par index et détecte optionnellement les éléments déplacés pour la lisibilité.
Q.Comment réviser un changement de réponse API ?
A.Capturez la réponse avant et après, canonicalisez les deux avec un formateur et faites le diff. Vous verrez immédiatement les champs ajoutés, supprimés ou modifiés sans être distrait par le bruit de formatage.
Q.Puis-je comparer des schémas JSON de la même façon ?
A.Oui, mais les schémas sont des documents où les noms de clés portent du sens, donc traitez-les comme des données ordonnées ou utilisez une comparaison consciente du schéma. Pour une revue rapide, canonicalisez et faites le diff exactement comme décrit ci-dessus.
Références
- RFC 8259 – The JavaScript Object Notation (JSON) Data Interchange Format : https://www.rfc-editor.org/rfc/rfc8259
- RFC 6902 – JavaScript Object Notation (JSON) Patch : https://www.rfc-editor.org/rfc/rfc6902
- RFC 7386 – JSON Merge Patch : https://www.rfc-editor.org/rfc/rfc7386
Comparez le JSON proprement
Canonicalisez avec le formateur JSON, puis faites le diff localement dans votre navigateur.
Choisissez le diff qui répond à votre question
Le diff texte trouve les changements d'octets ; le diff JSON sémantique trouve les changements de données. Pour la configuration et le travail API, normalisez d'abord, puis faites le diff – et vous obtenez les deux à moindre coût.
Formatez avec le formateur JSON et comparez avec l'outil de diff texte, tous deux côté client.