Un diff textuel sur du JSON est en général illisible, et la raison est structurelle. Deux documents peuvent être sémantiquement identiques et différer sur chaque ligne : clés dans un autre ordre, indentation différente, l'un minifié et l'autre formaté. Un outil ligne à ligne signale tout cela comme un changement, et le seul champ qui diffère vraiment est enfoui dans le bruit.
Une comparaison structurelle analyse d'abord les deux côtés puis compare les valeurs obtenues. L'ordre des clés cesse de compter, puisqu'un objet est par définition une table non ordonnée de clés vers des valeurs. Les espaces cessent de compter, puisqu'ils n'ont pas survécu à l'analyse. Reste la réponse à la question posée : quelles clés ont été ajoutées, lesquelles retirées, et lesquelles ont gardé leur clé en changeant de valeur.
Les tableaux sont l'endroit où la comparaison structurelle devient réellement difficile, et il vaut mieux savoir pourquoi que d'être surpris par le résultat. Un tableau est ordonné, donc la position porte du sens, et un élément inséré en tête décale tous les suivants d'un cran. Une comparaison positionnelle naïve signale alors chaque élément comme modifié, ce qui est techniquement vrai et inutile. Réordonner un tableau est un vrai changement et doit être signalé comme tel ; le conseil pratique est de lire un diff de tableau en gardant la question de l'ordre à l'esprit plutôt que comme une liste de modifications.
Les changements de type méritent une attention particulière car ce sont eux qui cassent les consommateurs en silence. Un champ qui valait le nombre 1 et vaut désormais la chaîne « 1 » paraît presque identique dans un diff affiché et se comporte différemment dans tous les langages stricts en aval. Il en va de même d'un null remplaçant une clé absente : les deux s'affichent comme rien dans beaucoup de visionneuses, et ils ne signifient pas la même chose pour un analyseur qui les distingue.
Les usages courants déterminent la façon de lire le résultat. Comparer une réponse d'API avant et après un déploiement dit ce qu'un changement a réellement modifié sur le fil, ce qui dépasse souvent ce qu'annonçaient les notes de version. Comparer deux fichiers de configuration entre environnements trouve le seul indicateur qui diffère et explique pourquoi la préproduction fonctionne et la production non. Comparer une donnée de test à une sortie réelle est la façon de diagnostiquer un échec en quelques secondes plutôt qu'en quelques minutes.
Les deux documents sont analysés et comparés dans votre onglet. Rien n'est envoyé, ce qui compte ici plus qu'ailleurs sur ce site, car comparer deux charges utiles de production revient à tenir deux jeux d'enregistrements clients réels dans la page en même temps.