4. Operationen
Operationsobjekte (Operation Object) MÜSSEN genau ein "op"-Mitglied haben, dessen Wert die auszuführende Operation angibt. Sein Wert MUSS einer von "add", "remove", "replace", "move", "copy" oder "test" sein; andere Werte sind Fehler. Die Semantik jedes Objekts ist unten definiert.
Zusätzlich MÜSSEN Operationsobjekte genau ein "path"-Mitglied haben. Der Wert dieses Mitglieds ist eine Zeichenkette, die einen JSON-Pointer-Wert [RFC6901] enthält, der auf einen Ort im Zieldokument (Target Document) (die "Zielposition", Target Location) verweist, an dem die Operation ausgeführt wird.
Die Bedeutungen anderer Operationsobjektmitglieder werden durch die Operation definiert (siehe die Unterabschnitte unten). Mitglieder, die für die betreffende Operation nicht explizit definiert sind, MÜSSEN ignoriert werden (d.h., die Operation wird abgeschlossen, als ob das undefinierte Mitglied nicht im Objekt erschienen wäre).
Beachten Sie, dass die Reihenfolge der Mitglieder in JSON-Objekten nicht signifikant ist; daher sind die folgenden Operationsobjekte äquivalent:
{ "op": "add", "path": "/a/b/c", "value": "foo" }
{ "path": "/a/b/c", "op": "add", "value": "foo" }
{ "value": "foo", "path": "/a/b/c", "op": "add" }
Operationen werden auf die durch ein JSON-Dokument dargestellten Datenstrukturen angewendet, d.h. nachdem jegliches Unescaping (siehe [RFC4627], Abschnitt 2.5) stattgefunden hat.
4.1. add
Die "add"-Operation führt eine der folgenden Funktionen aus, abhängig davon, worauf die Zielposition verweist:
-
Wenn die Zielposition einen Array-Index angibt, wird ein neuer Wert am angegebenen Index in das Array eingefügt.
-
Wenn die Zielposition ein Objektmitglied angibt, das noch nicht existiert, wird dem Objekt ein neues Mitglied hinzugefügt.
-
Wenn die Zielposition ein Objektmitglied angibt, das existiert, wird der Wert dieses Mitglieds ersetzt.
Das Operationsobjekt MUSS ein "value"-Mitglied enthalten, dessen Inhalt den hinzuzufügenden Wert angibt.
Zum Beispiel:
{ "op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ] }
Wenn die Operation angewendet wird, MUSS die Zielposition auf eines der folgenden verweisen:
-
Die Wurzel des Zieldokuments - wobei der angegebene Wert zum gesamten Inhalt des Zieldokuments wird.
-
Ein zu einem vorhandenen Objekt hinzuzufügendes Mitglied - wobei der bereitgestellte Wert an der angegebenen Stelle zu diesem Objekt hinzugefügt wird. Wenn das Mitglied bereits existiert, wird es durch den angegebenen Wert ersetzt.
-
Ein zu einem vorhandenen Array hinzuzufügendes Element - wobei der bereitgestellte Wert an der angegebenen Stelle zum Array hinzugefügt wird. Alle Elemente am oder über dem angegebenen Index werden um eine Position nach rechts verschoben. Der angegebene Index DARF NICHT größer sein als die Anzahl der Elemente im Array. Wenn das
"-"-Zeichen verwendet wird, um das Ende des Arrays zu indizieren (siehe [RFC6901]), hat dies den Effekt, den Wert an das Array anzuhängen.
Da diese Operation dazu konzipiert ist, zu vorhandenen Objekten und Arrays hinzuzufügen, wird ihre Zielposition oft nicht existieren. Obwohl somit der Fehlerbehandlungsalgorithmus des Zeigers aufgerufen wird, definiert diese Spezifikation das Fehlerbehandlungsverhalten für "add"-Zeiger so, dass dieser Fehler ignoriert und der Wert wie angegeben hinzugefügt wird.
Das Objekt selbst oder ein es enthaltendes Array muss jedoch existieren, und es bleibt ein Fehler, wenn dies nicht der Fall ist. Zum Beispiel ist ein "add" mit einer Zielposition von "/a/b", beginnend mit diesem Dokument:
{ "a": { "foo": 1 } }
kein Fehler, weil "a" existiert und "b" zu seinem Wert hinzugefügt wird. Es ist ein Fehler in diesem Dokument:
{ "q": { "bar": 2 } }
weil "a" nicht existiert.
4.2. remove
Die "remove"-Operation entfernt den Wert an der Zielstelle.
Die Zielstelle MUSS (MUST) existieren, damit die Operation erfolgreich ist.
Zum Beispiel:
{ "op": "remove", "path": "/a/b/c" }
Wenn ein Element aus einem Array entfernt wird, werden alle Elemente oberhalb des angegebenen Index um eine Position nach links verschoben.
4.3. replace
Die "replace"-Operation ersetzt den Wert an der Zielstelle durch einen neuen Wert. Das Operationsobjekt MUSS (MUST) ein "value"-Mitglied enthalten, dessen Inhalt den Ersatzwert angibt.
Die Zielstelle MUSS (MUST) existieren, damit die Operation erfolgreich ist.
Zum Beispiel:
{ "op": "replace", "path": "/a/b/c", "value": 42 }
Diese Operation ist funktional identisch mit einer "remove"-Operation für einen Wert, gefolgt von einer "add"-Operation an derselben Stelle mit dem Ersatzwert.
4.4. move
Die "move"-Operation entfernt den Wert an einer angegebenen Stelle und fügt ihn an der Zielstelle hinzu.
Das Operationsobjekt MUSS (MUST) ein "from"-Mitglied enthalten, das eine Zeichenkette ist, die einen JSON Pointer-Wert enthält, der die Stelle im Zieldokument referenziert, von der der Wert verschoben werden soll.
Die "from"-Stelle MUSS (MUST) existieren, damit die Operation erfolgreich ist.
Zum Beispiel:
{ "op": "move", "from": "/a/b/c", "path": "/a/b/d" }
Diese Operation ist funktional identisch mit einer "remove"-Operation an der "from"-Stelle, gefolgt von einer "add"-Operation an der Zielstelle mit dem Wert, der gerade entfernt wurde.
Die "from"-Stelle DARF NICHT (MUST NOT) ein echtes Präfix der "path"-Stelle sein; d.h., eine Stelle kann nicht in eines ihrer Kinder verschoben werden.
4.5. copy
Die "copy"-Operation kopiert den Wert an einer angegebenen Stelle zur Zielstelle.
Das Operationsobjekt MUSS (MUST) ein "from"-Mitglied enthalten, das eine Zeichenkette ist, die einen JSON Pointer-Wert enthält, der die Stelle im Zieldokument referenziert, von der der Wert kopiert werden soll.
Die "from"-Stelle MUSS (MUST) existieren, damit die Operation erfolgreich ist.
Zum Beispiel:
{ "op": "copy", "from": "/a/b/c", "path": "/a/b/e" }
Diese Operation ist funktional identisch mit einer "add"-Operation an der Zielstelle unter Verwendung des im "from"-Mitglied angegebenen Werts.
4.6. test
Die "test"-Operation testet, ob ein Wert an der Zielstelle gleich einem angegebenen Wert ist.
Das Operationsobjekt MUSS (MUST) ein "value"-Mitglied enthalten, das den Wert übermittelt, der mit dem Wert der Zielstelle verglichen werden soll.
Die Zielstelle MUSS (MUST) gleich dem "value"-Wert sein, damit die Operation als erfolgreich angesehen wird.
Hier bedeutet "gleich" (equal), dass der Wert an der Zielstelle und der von "value" übermittelte Wert vom gleichen JSON-Typ sind und nach den folgenden Regeln für diesen Typ als gleich angesehen werden:
-
strings (Zeichenketten): werden als gleich angesehen, wenn sie die gleiche Anzahl von Unicode-Zeichen enthalten und ihre Codepunkte byteweise gleich sind.
-
numbers (Zahlen): werden als gleich angesehen, wenn ihre Werte numerisch gleich sind.
-
arrays (Arrays): werden als gleich angesehen, wenn sie die gleiche Anzahl von Werten enthalten und jeder Wert als gleich mit dem Wert an der entsprechenden Position im anderen Array angesehen werden kann, unter Verwendung dieser Liste typspezifischer Regeln.
-
objects (Objekte): werden als gleich angesehen, wenn sie die gleiche Anzahl von Mitgliedern enthalten und jedes Mitglied als gleich mit einem Mitglied im anderen Objekt angesehen werden kann, indem ihre Schlüssel (als Zeichenketten) und ihre Werte (unter Verwendung dieser Liste typspezifischer Regeln) verglichen werden.
-
literals (Literale) (false, true, und null): werden als gleich angesehen, wenn sie identisch sind.
Beachten Sie, dass der durchgeführte Vergleich ein logischer Vergleich ist; z.B. ist Leerzeichen zwischen den Mitgliedswerten eines Arrays nicht signifikant. Beachten Sie auch, dass die Reihenfolge der Serialisierung von Objektmitgliedern nicht signifikant ist.
Zum Beispiel:
{ "op": "test", "path": "/a/b/c", "value": "foo" }