Aller au contenu principal

4. Opérations

Les objets d'opération (Operation Object) DOIVENT avoir exactement un membre "op", dont la valeur indique l'opération à effectuer. Sa valeur DOIT être l'une des suivantes: "add", "remove", "replace", "move", "copy" ou "test"; les autres valeurs sont des erreurs. La sémantique de chaque objet est définie ci-dessous.

De plus, les objets d'opération DOIVENT avoir exactement un membre "path". La valeur de ce membre est une chaîne contenant une valeur JSON-Pointer [RFC6901] qui référence un emplacement dans le document cible (Target Document) (l'"emplacement cible", Target Location) où l'opération est effectuée.

Les significations des autres membres de l'objet d'opération sont définies par l'opération (voir les sous-sections ci-dessous). Les membres qui ne sont pas explicitement définis pour l'opération en question DOIVENT être ignorés (c'est-à-dire que l'opération se terminera comme si le membre non défini n'apparaissait pas dans l'objet).

Notez que l'ordre des membres dans les objets JSON n'est pas significatif; par conséquent, les objets d'opération suivants sont équivalents:

{ "op": "add", "path": "/a/b/c", "value": "foo" }
{ "path": "/a/b/c", "op": "add", "value": "foo" }
{ "value": "foo", "path": "/a/b/c", "op": "add" }

Les opérations sont appliquées aux structures de données représentées par un document JSON, c'est-à-dire après tout échappement (voir [RFC4627], Section 2.5).

4.1. add​

L'opération "add" effectue l'une des fonctions suivantes, selon ce que l'emplacement cible référence:

  • Si l'emplacement cible spécifie un index de tableau, une nouvelle valeur est insérée dans le tableau à l'index spécifié.

  • Si l'emplacement cible spécifie un membre d'objet qui n'existe pas encore, un nouveau membre est ajouté à l'objet.

  • Si l'emplacement cible spécifie un membre d'objet qui existe, la valeur de ce membre est remplacée.

L'objet d'opération DOIT contenir un membre "value" dont le contenu spécifie la valeur à ajouter.

Par exemple:

{ "op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ] }

Lorsque l'opération est appliquée, l'emplacement cible DOIT référencer l'un des éléments suivants:

  • La racine du document cible - auquel cas la valeur spécifiée devient le contenu entier du document cible.

  • Un membre à ajouter à un objet existant - auquel cas la valeur fournie est ajoutée à cet objet à l'emplacement indiqué. Si le membre existe déjà, il est remplacé par la valeur spécifiée.

  • Un élément à ajouter à un tableau existant - auquel cas la valeur fournie est ajoutée au tableau à l'emplacement indiqué. Tous les éléments à l'index spécifié ou au-dessus sont décalés d'une position vers la droite. L'index spécifié NE DOIT PAS être supérieur au nombre d'éléments dans le tableau. Si le caractère "-" est utilisé pour indexer la fin du tableau (voir [RFC6901]), cela a pour effet d'ajouter la valeur au tableau.

Parce que cette opération est conçue pour ajouter à des objets et des tableaux existants, son emplacement cible n'existera souvent pas. Bien que l'algorithme de gestion des erreurs du pointeur soit ainsi invoqué, cette spécification définit le comportement de gestion des erreurs pour les pointeurs "add" pour ignorer cette erreur et ajouter la valeur comme spécifié.

Cependant, l'objet lui-même ou un tableau le contenant doit exister, et il reste une erreur si ce n'est pas le cas. Par exemple, un "add" avec un emplacement cible de "/a/b" commençant par ce document:

{ "a": { "foo": 1 } }

n'est pas une erreur, car "a" existe, et "b" sera ajouté à sa valeur. C'est une erreur dans ce document:

{ "q": { "bar": 2 } }

car "a" n'existe pas.

4.2. remove​

L'opération "remove" supprime la valeur à l'emplacement cible.

L'emplacement cible DOIT (MUST) exister pour que l'opération réussisse.

Par exemple:

{ "op": "remove", "path": "/a/b/c" }

Si un élément est supprimé d'un tableau, tous les éléments situés au-dessus de l'index spécifié sont décalés d'une position vers la gauche.

4.3. replace​

L'opération "replace" remplace la valeur à l'emplacement cible par une nouvelle valeur. L'objet d'opération DOIT (MUST) contenir un membre "value" dont le contenu spécifie la valeur de remplacement.

L'emplacement cible DOIT (MUST) exister pour que l'opération réussisse.

Par exemple:

{ "op": "replace", "path": "/a/b/c", "value": 42 }

Cette opération est fonctionnellement identique à une opération "remove" pour une valeur, suivie immédiatement d'une opération "add" au même emplacement avec la valeur de remplacement.

4.4. move​

L'opération "move" supprime la valeur à un emplacement spécifié et l'ajoute à l'emplacement cible.

L'objet d'opération DOIT (MUST) contenir un membre "from", qui est une chaîne contenant une valeur JSON Pointer qui référence l'emplacement dans le document cible à partir duquel déplacer la valeur.

L'emplacement "from" DOIT (MUST) exister pour que l'opération réussisse.

Par exemple:

{ "op": "move", "from": "/a/b/c", "path": "/a/b/d" }

Cette opération est fonctionnellement identique à une opération "remove" sur l'emplacement "from", suivie immédiatement d'une opération "add" à l'emplacement cible avec la valeur qui vient d'être supprimée.

L'emplacement "from" NE DOIT PAS (MUST NOT) être un préfixe propre de l'emplacement "path"; c'est-à-dire qu'un emplacement ne peut pas être déplacé dans l'un de ses enfants.

4.5. copy​

L'opération "copy" copie la valeur à un emplacement spécifié vers l'emplacement cible.

L'objet d'opération DOIT (MUST) contenir un membre "from", qui est une chaîne contenant une valeur JSON Pointer qui référence l'emplacement dans le document cible à partir duquel copier la valeur.

L'emplacement "from" DOIT (MUST) exister pour que l'opération réussisse.

Par exemple:

{ "op": "copy", "from": "/a/b/c", "path": "/a/b/e" }

Cette opération est fonctionnellement identique à une opération "add" à l'emplacement cible en utilisant la valeur spécifiée dans le membre "from".

4.6. test​

L'opération "test" teste qu'une valeur à l'emplacement cible est égale à une valeur spécifiée.

L'objet d'opération DOIT contenir un membre "value" qui transmet la valeur à comparer à la valeur de l'emplacement cible.

L'emplacement cible DOIT être égal à la valeur "value" pour que l'opération soit considérée comme réussie.

Ici, "égal" signifie que la valeur à l'emplacement cible et la valeur transmise par "value" sont du même type JSON, et qu'elles sont considérées comme égales selon les règles suivantes pour ce type:

  • chaînes: sont considérées comme égales si elles contiennent le même nombre de caractères Unicode et que leurs points de code sont égaux octet par octet.

  • nombres: sont considérés comme égaux si leurs valeurs sont numériquement égales.

  • tableaux: sont considérés comme égaux s'ils contiennent le même nombre de valeurs, et si chaque valeur peut être considérée comme égale à la valeur à la position correspondante dans l'autre tableau, en utilisant cette liste de règles spécifiques au type.

  • objets: sont considérés comme égaux s'ils contiennent le même nombre de membres, et si chaque membre peut être considéré comme égal à un membre dans l'autre objet, en comparant leurs clés (en tant que chaînes) et leurs valeurs (en utilisant cette liste de règles spécifiques au type).

  • littéraux (false, true et null): sont considérés comme égaux s'ils sont identiques.

Notez que la comparaison effectuée est une comparaison logique; par exemple, l'espace blanc entre les valeurs des membres d'un tableau n'est pas significatif.

De plus, notez que l'ordre de la sérialisation des membres d'objet n'est pas significatif.

Par exemple:

{ "op": "test", "path": "/a/b/c", "value": "foo" }