Un nom de membre n’est pas encore un chemin
Imaginez un objet JSON dont la clé est draft/a~b et dont la valeur contient un autre objet avec state. La barre fait partie de la clé ; elle ne crée pas un niveau supplémentaire. JSON Pointer identifie au contraire une valeur par des segments séparés par des barres. Le chemin /orders/0/item peut désigner un élément de tableau, où 0 est l’indice. Copier directement un nom de membre dans un chemin peut donc viser un mauvais endroit ou échouer.
La RFC 6901 définit deux échappements à l’intérieur de chaque segment : le tilde devient ~0 et la barre devient ~1. Le pointeur complet commence aussi par une barre pour chaque segment, tandis que le pointeur vide désigne le document entier. Cette notation porte sur l’adresse et ne modifie ni la valeur ni l’objet JSON. Employez l’outil d’échappement de segment lorsque vous bâtissez un chemin à partir d’un nom reçu dans des données ou fourni par un utilisateur.
Construire l’exemple segment par segment
Pour la clé draft/a~b, remplacez d’abord le tilde par ~0 puis la barre par ~1. Le segment échappé est draft~1a~0b. Ajoutez une barre initiale puis le membre distinct state : vous obtenez /draft~1a~0b/state. Le convertisseur intégré effectue seulement l’étape du segment ; il n’ajoute volontairement pas la première barre, car ce segment peut se placer ailleurs dans un chemin plus long. Comparez son résultat aux trois étapes du schéma.
L’outil inverse remplace ~1 par la barre avant de remplacer ~0 par le tilde. Cet ordre compte : décoder ~01 en ~1, puis encore une fois en barre, changerait le nom de départ. Un segment JSON Pointer n’est pas non plus un encodage en pourcentage d’URL. Si vous l’insérez dans un fragment d’adresse web, cette couche extérieure suit des règles supplémentaires. Gardez distinctes la syntaxe du pointeur et celle de l’URL en examinant un lien ou une requête.
- Clé brute : draft/a~b
- Segment échappé : draft~1a~0b
- Chemin complet : /draft~1a~0b/state
Ce que produit réellement l’aplatissement
L’outil d’aplatissement parcourt un objet JSON et place les valeurs terminales sous des clés qui ressemblent à des JSON Pointers complets. Si state se trouve sous draft/a~b, une entrée plate sera /draft~1a~0b/state avec la même valeur terminale. Cette vue facilite la comparaison, l’inventaire ou l’export des données imbriquées. L’outil inverse lit ces clés pour recréer un objet si les chemins ne se contredisent pas. Une entrée plate demeure une propriété JSON et n’effectue pas automatiquement une recherche.
Dans cette implémentation, les tableaux sont des valeurs terminales : elle ne produit pas d’entrées distinctes /0 et /1. Les objets vides sont également terminaux. Un JSON Pointer général peut pourtant désigner un indice de tableau ; la liste aplatie de cet outil ne les énumère simplement pas. Si /a reçoit une valeur simple alors que /a/b exige un objet, le retour doit refuser le conflit. Conservez le JSON d’origine avant de modifier les clés manuellement.
Méthode pour travailler avec des chemins
Commencez par un JSON valide et choisissez entre une adresse unique et une vue aplatie complète. Pour une adresse, séparez les véritables noms de membres, échappez chaque nom indépendamment, puis réunissez les segments avec leurs barres initiales. N’échappez pas tout le pointeur d’un seul coup : ses barres séparatrices deviendraient des caractères de nom. Pour examiner de nombreuses valeurs terminales, aplatissez l’objet et vérifiez les clés générées avant de les envoyer ailleurs.
À la restauration, contrôlez que chaque clé plate commence par une barre et que ses séquences ~ sont valides. Surveillez les affectations répétées ou incompatibles, les tableaux laissés en bloc et les noms littéraux contenant points ou barres. Faites un essai aller-retour avec un petit objet contenant les deux caractères spéciaux, puis comparez les structures JSON analysées plutôt que l’indentation. La norme définit le pointeur ; la politique d’aplatissement précise appartient à ce convertisseur local.