Passa al contenuto principale

4. Operazioni

Gli oggetti operazione (Operation Object) DEVONO avere esattamente un membro "op", il cui valore indica l'operazione da eseguire. Il suo valore DEVE essere uno tra "add", "remove", "replace", "move", "copy" o "test"; altri valori sono errori. La semantica di ciascun oggetto è definita di seguito.

Inoltre, gli oggetti operazione DEVONO avere esattamente un membro "path". Il valore di quel membro è una stringa contenente un valore JSON-Pointer [RFC6901] che fa riferimento a una posizione all'interno del documento di destinazione (Target Document) (la "posizione di destinazione", Target Location) dove viene eseguita l'operazione.

I significati degli altri membri dell'oggetto operazione sono definiti dall'operazione (vedere le sottosezioni seguenti). I membri che non sono esplicitamente definiti per l'operazione in questione DEVONO essere ignorati (cioè, l'operazione verrà completata come se il membro non definito non fosse apparso nell'oggetto).

Si noti che l'ordine dei membri negli oggetti JSON non è significativo; pertanto, i seguenti oggetti operazione sono equivalenti:

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

Le operazioni vengono applicate alle strutture dati rappresentate da un documento JSON, cioè dopo che si è verificato qualsiasi unescaping (vedere [RFC4627], Sezione 2.5).

4.1. add​

L'operazione "add" esegue una delle seguenti funzioni, a seconda di ciò a cui fa riferimento la posizione di destinazione:

  • Se la posizione di destinazione specifica un indice di array, un nuovo valore viene inserito nell'array all'indice specificato.

  • Se la posizione di destinazione specifica un membro oggetto che non esiste ancora, viene aggiunto un nuovo membro all'oggetto.

  • Se la posizione di destinazione specifica un membro oggetto che esiste, il valore di quel membro viene sostituito.

L'oggetto operazione DEVE contenere un membro "value" il cui contenuto specifica il valore da aggiungere.

Ad esempio:

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

Quando l'operazione viene applicata, la posizione di destinazione DEVE fare riferimento a uno dei seguenti:

  • La radice del documento di destinazione - nel qual caso il valore specificato diventa l'intero contenuto del documento di destinazione.

  • Un membro da aggiungere a un oggetto esistente - nel qual caso il valore fornito viene aggiunto a quell'oggetto nella posizione indicata. Se il membro esiste già, viene sostituito dal valore specificato.

  • Un elemento da aggiungere a un array esistente - nel qual caso il valore fornito viene aggiunto all'array nella posizione indicata. Tutti gli elementi all'indice specificato o superiori vengono spostati di una posizione a destra. L'indice specificato NON DEVE essere maggiore del numero di elementi nell'array. Se viene utilizzato il carattere "-" per indicizzare la fine dell'array (vedere [RFC6901]), ciò ha l'effetto di aggiungere il valore all'array.

Poiché questa operazione è progettata per aggiungere a oggetti e array esistenti, la sua posizione di destinazione spesso non esisterà. Sebbene venga quindi invocato l'algoritmo di gestione degli errori del puntatore, questa specifica definisce il comportamento di gestione degli errori per i puntatori "add" per ignorare tale errore e aggiungere il valore come specificato.

Tuttavia, l'oggetto stesso o un array che lo contiene deve esistere, e rimane un errore se questo non è il caso. Ad esempio, un "add" con una posizione di destinazione di "/a/b" che inizia con questo documento:

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

non è un errore, perché "a" esiste e "b" verrà aggiunto al suo valore. È un errore in questo documento:

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

perché "a" non esiste.

4.2. remove​

L'operazione "remove" rimuove il valore nella posizione di destinazione.

La posizione di destinazione DEVE (MUST) esistere affinché l'operazione abbia successo.

Ad esempio:

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

Se un elemento viene rimosso da un array, tutti gli elementi superiori all'indice specificato vengono spostati di una posizione a sinistra.

4.3. replace​

L'operazione "replace" sostituisce il valore nella posizione di destinazione con un nuovo valore. L'oggetto operazione DEVE (MUST) contenere un membro "value" il cui contenuto specifica il valore di sostituzione.

La posizione di destinazione DEVE (MUST) esistere affinché l'operazione abbia successo.

Ad esempio:

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

Questa operazione è funzionalmente identica a un'operazione "remove" per un valore, seguita immediatamente da un'operazione "add" nella stessa posizione con il valore di sostituzione.

4.4. move​

L'operazione "move" rimuove il valore in una posizione specificata e lo aggiunge alla posizione di destinazione.

L'oggetto operazione DEVE (MUST) contenere un membro "from", che è una stringa contenente un valore JSON Pointer che fa riferimento alla posizione nel documento di destinazione da cui spostare il valore.

La posizione "from" DEVE (MUST) esistere affinché l'operazione abbia successo.

Ad esempio:

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

Questa operazione è funzionalmente identica a un'operazione "remove" nella posizione "from", seguita immediatamente da un'operazione "add" nella posizione di destinazione con il valore appena rimosso.

La posizione "from" NON DEVE (MUST NOT) essere un prefisso proprio della posizione "path"; cioè, una posizione non può essere spostata in uno dei suoi figli.

4.5. copy​

L'operazione "copy" copia il valore in una posizione specificata alla posizione di destinazione.

L'oggetto operazione DEVE (MUST) contenere un membro "from", che è una stringa contenente un valore JSON Pointer che fa riferimento alla posizione nel documento di destinazione da cui copiare il valore.

La posizione "from" DEVE (MUST) esistere affinché l'operazione abbia successo.

Ad esempio:

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

Questa operazione è funzionalmente identica a un'operazione "add" nella posizione di destinazione utilizzando il valore specificato nel membro "from".

4.6. test​

L'operazione "test" verifica che un valore nella posizione di destinazione sia uguale a un valore specificato.

L'oggetto operazione DEVE (MUST) contenere un membro "value" che trasmette il valore da confrontare con il valore della posizione di destinazione.

La posizione di destinazione DEVE (MUST) essere uguale al valore "value" affinché l'operazione sia considerata riuscita.

Qui, "uguale" (equal) significa che il valore nella posizione di destinazione e il valore trasmesso da "value" sono dello stesso tipo JSON, e che sono considerati uguali secondo le seguenti regole per quel tipo:

  • strings (stringhe): sono considerate uguali se contengono lo stesso numero di caratteri Unicode e i loro punti di codice sono uguali byte per byte.

  • numbers (numeri): sono considerati uguali se i loro valori sono numericamente uguali.

  • arrays (array): sono considerati uguali se contengono lo stesso numero di valori, e se ogni valore può essere considerato uguale al valore nella posizione corrispondente nell'altro array, utilizzando questo elenco di regole specifiche per tipo.

  • objects (oggetti): sono considerati uguali se contengono lo stesso numero di membri, e se ogni membro può essere considerato uguale a un membro nell'altro oggetto, confrontando le loro chiavi (come stringhe) e i loro valori (utilizzando questo elenco di regole specifiche per tipo).

  • literals (letterali) (false, true, e null): sono considerati uguali se sono identici.

Si noti che il confronto eseguito è un confronto logico; ad esempio, lo spazio bianco tra i valori dei membri di un array non è significativo. Si noti inoltre che l'ordine della serializzazione dei membri dell'oggetto non è significativo.

Ad esempio:

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