JSON Pointer, RFC 6901, est une petite spécification : quatre pages, une
syntaxe, aucune ambiguïté sur ce que signifie un chemin. Il apparaît là
où quelque chose a besoin de référencer un emplacement exact à l’intérieur
d’un document JSON sans inventer son propre langage de chemins, le plus
souvent à l’intérieur de JSON Schema et du mot-clé $ref de JSON Schema.
La syntaxe, en bref
Un pointeur est une séquence de jetons séparés par /. /user/name
signifie la clé name à l’intérieur de l’objet user. /items/0
signifie le premier élément du tableau items. La chaîne vide, un
pointeur sans jeton du tout, signifie le document entier. Deux
caractères nécessitent un échappement à l’intérieur d’un jeton : ~1
représente un / littéral, et ~0 représente un ~ littéral, toujours
lu dans cet ordre pour que ~01 signifie ~1 plutôt que /.
Utiliser l’évaluateur JSON Pointer
Collez un document, tapez un pointeur, et appuyez sur Résoudre. Étant donné
{"a/b":{"c~d":42},"list":["x","y"]}le pointeur /a~1b/c~0d résout à travers une clé qui contient
littéralement une barre et une clé qui contient littéralement un tilde,
renvoyant 42. C’est toute la raison pour laquelle les échappements
existent : sans eux, une clé contenant le caractère séparateur serait
impossible à adresser.
Ce que vous dit une recherche échouée
La plupart des outils signalent un pointeur échoué comme un simple “non
trouvé”, ce qui n’est pas suffisant pour le corriger dans un document
avec plus de quelques clés. Celui-ci vous dit où le pointeur est arrivé,
ce qu’il a trouvé là, et quelles clés l’objet a réellement. Demander
/a~1b/nope contre le même document renvoie :
Pas de clé “nope” dans l’objet ici, il a c
d. Résolu jusqu’à /a1b
C’est suffisant pour voir la faute de frappe immédiatement, plutôt que relire tout le document pour deviner ce qui s’est mal passé.
Le tiret, et pourquoi il ne résout pas
À l’intérieur de JSON Schema, un tiret comme le dernier jeton d’un
pointeur vers un tableau signifie “la position après le dernier élément”,
utilisé pour l’ajout. Seul, résoudre /items/- contre un document ne
nomme pas une valeur existante, car il n’y a encore rien là où pointer.
L’évaluateur explique cette distinction plutôt que de la traiter comme
une erreur d’analyse générique.
Où cela diffère de JSONPath
JSON Pointer nomme un emplacement et résout à exactement une valeur ou échoue. JSONPath est un langage de requêtes qui peut correspondre à plusieurs valeurs à la fois, avec des jokers, des filtres et des tranches. Utilisez un pointeur quand vous savez exactement quelle valeur vous voulez ; utilisez JSONPath quand vous recherchez des valeurs qui correspondent à une condition.