Pointeur JSON : évaluateur de pointeurs RFC 6901

Qu’est-ce qu’un pointeur JSON ?

Un pointeur JSON est une courte chaîne qui désigne exactement un endroit dans un document JSON. C’est une suite de jetons, chacun introduit par une barre oblique : /paths/~1users/get descend ainsi de la racine vers le membre nommé paths, puis vers celui nommé /users, puis vers get. La RFC 6901 le définit en huit pages, et c’est ce qu’emploient JSON Patch, les références de JSON Schema et OpenAPI pour dire de quoi ils parlent.

Le mot qui compte est exactement. Un pointeur désigne un endroit, et soit il s’y trouve quelque chose, soit non — ce qui le distingue de JSONPath, où une seule requête peut renvoyer cent nœuds ou aucun, et où les implémentations ne renvoient pas les mêmes ensembles. Dans un pointeur il n’y a rien sur quoi diverger, et c’est précisément pourquoi les formats qui doivent être sans ambiguïté l’ont retenu.

Cette grammaire minuscule a plus d’angles qu’il n’y paraît, et cet outil les montre tous. Collez un document, écrivez un pointeur, et il évalue jeton par jeton : dans quoi chacun a été cherché, ce qu’il a trouvé et, quand il n’a rien trouvé, quelle règle l’a arrêté.

Comment l’utiliser

1. Collez un document. L’outil démarre sur le document donné en exemple par la norme : toutes les réponses se vérifient donc dans la RFC 6901 elle-même. Ce qui n’est pas du JSON valide vous est signalé plutôt que deviné.
2. Écrivez un pointeur. La chaîne vide désigne le document entier ; tout le reste commence par une barre oblique. Dans un jeton, le tilde s’écrit ~0 et la barre oblique ~1. Ou choisissez-en un dans la liste de tous les pointeurs de votre document, en bas.
3. Lisez la trace. Chaque ligne montre un jeton, s’il a été cherché dans un objet ou dans un tableau, et ce qui est revenu. Un échec nomme la règle précise au lieu de se contenter de ne rien renvoyer.

La règle d’échappement, et l’ordre qu’elle impose

Deux caractères ne peuvent pas figurer tels quels dans un jeton. La barre oblique ouvrirait un nouveau jeton et le tilde est le caractère d’échappement : on écrit donc ~1 et ~0. Voilà tout le dispositif, et il est plus réduit qu’on ne l’imagine : ni barre oblique inverse, ni encodage pour cent, ni aucun autre échappement. Un tilde suivi d’autre chose que 0 ou 1 n’est pas un pointeur valide.

L’intéressant est l’ordre. Le décodage doit transformer ~1 en barre oblique d’abord, et ~0 en tilde ensuite. Dans l’autre sens, ~01 devient ~1 puis une barre oblique, alors que la bonne réponse est les deux caractères ~1. La norme y consacre un paragraphe entier et nomme explicitement le résultat erroné — ce qui indique en général que des implémentations réelles se trompent. Cet outil décode en une seule passe : le danger n’est donc pas évité en se souvenant d’un ordre, il ne peut tout simplement pas se produire.

L’encodage pose le même piège à l’envers : il faut échapper le tilde avant la barre oblique, faute de quoi un nom contenant une barre produit un jeton qui se décode en autre chose. L’outil échappe au fil du parcours, pour cette raison.

Quatre règles qui surprennent

Un indice de tableau ne peut pas porter de zéro initial. La grammaire admet un zéro seul, ou un chiffre de un à neuf suivi de chiffres quelconques, et rien d’autre : /foo/01 est donc une erreur de syntaxe et non l’indice un. C’est exactement là qu’une implémentation en JavaScript dérape, car les deux façons évidentes de lire un nombre l’acceptent : l’une transforme le texte 01 en le nombre un, l’autre extrait un nombre du début de 1abc et jette le reste. Ni l’une ni l’autre ne correspond à la grammaire.

Une barre oblique seule n’est pas un pointeur vide. C’est un jeton dont le nom est la chaîne vide : il désigne donc le membre appelé rien du tout, un nom de membre parfaitement légal en JSON, et que le document d’exemple de la norme comporte précisément pour cette raison. Le pointeur vide, sans aucun caractère, est celui qui désigne le document entier.

Le caractère - seul désigne la position suivant le dernier élément d’un tableau. Ce n’est pas un indice et il n’y a jamais de valeur à cet endroit ; il existe pour que JSON Patch puisse dire ajoute ici. L’annoncer comme une erreur serait faux et renvoyer une valeur serait un mensonge : l’outil lui réserve donc une réponse à part.

Les noms de membres se comparent point de code par point de code, et la norme précise clairement qu’aucune normalisation Unicode n’est appliquée. Deux écritures de la même lettre accentuée — l’une composée en un seul caractère, l’autre écrite comme lettre plus signe combinant — sont identiques à l’œil et constituent deux membres distincts. Si un pointeur qui semble correct refuse de se résoudre, c’est la première chose à vérifier.

La forme de fragment, et ce qu’elle ne signifie pas

Un pointeur peut aussi s’écrire dans un fragment d’URI, et la norme redonne les mêmes douze exemples sous cette forme : le pointeur est encodé en UTF-8 et tout ce qu’un fragment ne peut porter est encodé pour cent, si bien que le signe pour cent devient %25 et l’espace %20. L’outil affiche cette écriture pour ce que vous tapez et vous laisse la copier.

Vient alors la phrase que presque personne ne devinerait, dans la section même qui imprime ces exemples : la syntaxe d’identifiant de fragment d’application/json n’est pas le pointeur JSON. Un type de média doit déclarer explicitement le pointeur JSON comme sa syntaxe de fragment, ce que le JSON tout court n’a jamais fait. Une URL se terminant par un pointeur a donc un sens dans un JSON Schema ou une référence OpenAPI, où le format le prévoit, et n’est qu’ornement sur un .json ordinaire, où rien ne le lui confère.

Il vaut la peine de dire aussi où s’arrête l’outil. Il évalue des pointeurs et n’applique pas de correctifs ; la RFC 6902 s’appuie sur cette grammaire pour ajouter, retirer et déplacer des valeurs, et c’est un autre métier. Il travaille sur le document que vous collez, sans suivre de références vers d’autres fichiers. Et il est strict à dessein : là où une bibliothèque accepterait en silence un zéro initial ou un tilde isolé, il vous nomme la règle enfreinte — car un pointeur qui fonctionne dans une implémentation et échoue dans une autre est précisément le problème qu’il sert à éviter.

Pourquoi est-ce gratuit ?

Parcourir un document jeton par jeton représente quelques centaines de lignes de manipulation de chaînes, et votre navigateur s’en charge pendant que vous tapez. Aucun serveur ne voit votre JSON : il n’y a donc rien à facturer ni de compte à créer.

Rien n’est envoyé. Ce que vous collez reste dans cet onglet.