Le pointeur JSON et JSONPath addressent tous deux des emplacements à l'intérieur d'un document JSON, et
tous deux apparaissent dans les mêmes types d'outils : $ref dans JSON Schema, opérations
PATCH, basée sur les chemins. Ils résolvent des problèmes différents, et savoir lequel
une tâche donnée nécessite réellement évite de choisir le mauvais outil.
Pointeur JSON : un emplacement, RFC 6901
Un pointeur est une séquence de jetons séparés par / : /user/name désigne la
clé name à l'intérieur de l'objet user, /items/0 désigne le premier élément du
tableau items. Deux caractères nécessitent d'être échappés à l'intérieur d'un jeton (~1 pour un
/ littéral, ~0 pour un ~ littéral), et la chaîne vide en tant que pointeur
signifie l'entier document. C'est toute la grammaire. Un pointeur résout à
exactement une valeur, ou échoue, sans rien entre les deux : pas de joker, pas de filtre, pas de
moyen de correspondre à plus d'un emplacement qu'il nomme.
{ "user": { "name": "Ada", "roles": ["admin", "editor"] } }/user/name résout à "Ada". /user/roles/1 résout à "editor".
/user/email échoue, car cette clé n'existe pas. Rien dans la
syntaxe du pointeur ne peut demander “tous les rôles” en une seule expression ; l'appelant
doit déjà connaître l'indice.
JSONPath : un langage de requêtes
JSONPath, standardisé en RFC 9535, est conçu pour la correspondance, pas seulement
l'adressage. $.user.roles[*] retourne les deux rôles dans l'exemple ci-dessus en
une seule requête. $..email recherche à chaque niveau du document toute clé
nommée email, peu importe la profondeur de l'imbrication. Les expressions de filtre comme
$.items[?(@.price > 100)] sélectionnent des éléments du tableau par une condition sur leur
propre contenu. Une requête JSONPath peut retourner zéro correspondance, une, ou plusieurs, ce qui
est un contrat fondamentalement différent de résoudre-ou-échouer d'un pointeur.
La différence pratique
Un pointeur nomme un emplacement que vous connaissez déjà. Une requête JSONPath décrit une condition et laisse le moteur trouver ce qui la satisfait. Cette différence détermine lequel convient à un travail donné :
- Vous savez exactement quelle valeur vous voulez (“le troisième élément du tableau d'adresse de livraison”) : utilisez un pointeur. Il est plus simple, a un sens unique par document, et toutes les implémentations sont d'accord sur ce qu'il fait, car le RFC laisse peu de place aux différences de dialecte.
- Vous recherchez des valeurs correspondant à une condition, ou vous ne connaissez
pas le chemin exact à l'avance (“chaque objet avec un
statusdefailed, ou qu'il apparaît”) : utilisez JSONPath. C'est aussi là où les différences de dialecte commencent à compter : les implémentations de JSONPath varient plus que ce que suggèrent les propres exemples de la RFC 9535, donc une requête écrite pour une bibliothèque n'est pas garantie de se comporter de manière identique dans une autre.
Où chacun apparaît en pratique
Les opérations JSON Patch (RFC 6902) utilisent exclusivement des pointeurs ; chaque "path"
d'une opération add, remove, replace ou move est un pointeur JSON,
car une opération de correctif vise un emplacement exact par conception. Le mot
clé $ref de JSON Schema résout également via la syntaxe de pointeur, pour la même
raison : une référence de schéma pointe vers une définition, pas un ensemble de celles-ci.
JSONPath apparaît là où une personne ou un outil doit interroger un document
de manière interactive : déboguer une grande réponse d'API, extraire un champ de
journaux, ou construire une règle qui doit correspondre à tout document avec une
forme donnée peu importe où se trouve le champ pertinent.
Essayer les deux
L'Évaluateur de Pointeur JSON résout un pointeur contre un document et, en cas d'échec de recherche, indique où il s'est arrêté et quelles clés existent réellement à ce point, plutôt qu'un simple “pas trouvé”. Le Testeur JSONPath exécute le sous-ensemble documenté de la RFC 9535 avec des extensions de fonctions, et la fiche JSONPath de ce blog a un exemple élaboré pour chaque sélecteur qui vaut la peine d'être connu. Comment utiliser le pointeur JSON traite de la syntaxe du pointeur en plus de détail, échappements inclus.