Aussi disponible en : English · Español · Português · العربية
JSON Patch : appliquez les opérations RFC 6902 pas à pas
Exécutez un correctif sur un document, voyez le résultat après chaque opération et découvrez ce qu’un échec laisse réellement derrière lui.
Qu’est-ce que JSON Patch ?
JSON Patch est un petit format pour décrire des modifications d’un document JSON plutôt que d’envoyer le document entier. Un correctif est un tableau d’opérations, chacune indiquant quoi faire et où : add, remove, replace, move, copy et test. La RFC 6902 définit les six en huit pages environ, et chaque emplacement s’écrit comme un pointeur JSON, le format frère qui désigne exactement un endroit dans un document.
Il existe parce qu’envoyer un document entier pour changer un champ est un gaspillage et, de surcroît, ambigu : deux clients qui procèdent ainsi s’écrasent mutuellement sans le savoir. Un correctif dit ce qui a changé, ce qui pèse moins et reste assez précis pour être refusé si le document a évolué entre-temps. C’est à cela que sert la sixième opération : test ne modifie rien, elle affirme, et un correctif commençant par un test est une modification qui refuse de s’appliquer au mauvais document.
Cette page exécute un correctif sur un document et affiche le résultat après chaque opération, pas seulement à la fin. Cela compte davantage qu’il n’y paraît, pour la raison qu’expose la section d’après.
Comment l’utiliser
- Collez le document. Il n’est jamais modifié sur place : chaque opération travaille sur une copie, votre document reste donc intact quoi que fasse le correctif.
- Collez le correctif. Un tableau d’opérations. Les boutons d’exemple chargent cinq cas : un test qui échoue à mi-parcours, une insertion dans un tableau, un test en garde-fou, un move que la norme interdit, et un indice au-delà de la fin d’un tableau.
- Lisez la trace. Chaque ligne est une opération, et vous pouvez déplier n’importe laquelle pour voir le document entier tel qu’il était à cet instant. Un échec nomme la règle précise au lieu de ne rien dire.
Un correctif JSON n’est pas atomique, et la norme ne dit pas qu’il l’est
Tout le monde sait qu’un correctif ayant échoué laisse le document intact. C’est la première chose qu’on vous dit du format, et ce n’est pas ce qu’écrit la RFC 6902.
Sa section 5 dit qu’en cas d’échec l’évaluation devrait s’arrêter et que l’application du correctif entier ne doit pas être réputée réussie. Lisez-le attentivement : c’est une affirmation sur le verdict, sur le fait que le correctif compte ou non comme appliqué. Elle ne dit rien de l’annulation des opérations déjà exécutées. L’atomicité que tout le monde cite arrive une phrase plus loin et vient d’ailleurs : une note signalant que la méthode HTTP PATCH est atomique, selon un autre document, celui qui définit cette méthode.
La garantie appartient donc au transport, non au format. Envoyez un correctif par HTTP PATCH et le serveur est tenu de tout appliquer ou rien. Confiez le même correctif à une bibliothèque dans votre propre processus, et vous retrouver avec un objet à moitié modifié relève de cette bibliothèque, pas d’une question que la norme tranche pour vous. L’exemple donné par la norme elle-même est un correctif de deux opérations dont le test échoue en second, et elle indique que le document finit inchangé — parce qu’elle décrit le cas HTTP.
Voilà pourquoi cet outil montre tous les états intermédiaires. Quand un correctif échoue ici, il écarte le résultat et vous le dit, ce qui est un choix et non une règle ; et il vous montre ce que le document était déjà devenu, précisément ce qu’un outil n’affichant que la réponse finale vous cache.
Trois règles qui surprennent
Ajouter dans un tableau insère, cela n’écrase pas. Pointez add sur l’indice un d’un tableau de trois éléments et vous en obtenez quatre, tout ce qui se trouvait à partir de l’indice un ayant glissé d’un cran. Si vous vouliez écraser, c’est replace. L’indice peut égaler la longueur, ce qui ajoute à la fin, mais au-delà c’est une erreur et non une écriture éparse — et la syntaxe des pointeurs comporte un tiret signifiant après le dernier élément, qui dit ajoute à la fin bien plus clairement qu’un nombre.
La même opération recèle un piège plus discret. Ajouter un tableau comme valeur l’insère entier en tant qu’élément unique : une liste d’un plus un tableau de deux devient donc une liste de deux, dont le second est lui-même une liste. La norme en fait un exemple à part, ce qui indique généralement qu’on s’attendait à l’inverse.
Move porte une règle sans équivalent parmi les autres opérations : la source ne peut pas être un préfixe propre de la destination ou, selon les mots mêmes de la norme, un emplacement ne peut pas être déplacé dans l’un de ses enfants. C’est évident une fois énoncé, et très facile à écrire par mégarde quand les chemins sont longs.
Enfin, test compare les types autant que les valeurs. Le nombre dix et la chaîne dix diffèrent, et un test opposant l’un à l’autre échoue. C’est le comportement qu’on attend d’une précondition, mais il piège quiconque arrive d’un formulaire ou d’une chaîne de requête, où tout est parvenu sous forme de texte.
Limites assumées
Cet outil applique des correctifs ; il n’en produit pas. Fabriquer le correctif minimal entre deux documents est un autre problème, aux réponses multiples et toutes défendables, et la norme n’en définit aucune.
Un exemple de la norme échappe à cet outil, et la raison mérite d’être connue. C’est un correctif dont l’objet d’opération contient deux fois le même membre — op y figure comme add puis comme remove — et la norme observe que JSON dit seulement que les noms de membres devraient être uniques, sans traitement standard des doublons. N’importe quel analyseur JavaScript tranche silencieusement en gardant le dernier : le défaut que l’exemple veut décrire est donc détruit avant qu’un moteur de correctifs ne voie le document. C’est une propriété de l’analyseur, non du format, et aucune implémentation recevant du JSON déjà analysé ne peut le détecter.
Enfin, cet outil écarte le résultat dès qu’une opération échoue. C’est délibéré et c’est le défaut le plus sûr, mais c’est une décision de cette page et non une contrainte du format — raison pour laquelle le document à moitié modifié est affiché à côté plutôt que jeté en silence.
Pourquoi est-ce gratuit ?
Parcourir un document et appliquer une poignée d’opérations représente quelques centaines de lignes de manipulation de chaînes et de tableaux, ce que votre navigateur fait 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.