JavaScript Object Notation (JSON) Patch
Extracted elements (22)
The "add" operation is designed to add to existing objects and arrays, so its target location will often not exist. The spec overrides the JSON Pointer error-handling algorithm to allow this, but the parent object or array must itself exist.
The structure of a JSON Patch document was influenced by the XML Patch document specification (RFC 5261), which similarly defines a sequence of patch operations applied to a target document.
The "test" operation's equality comparison is a logical comparison, not a serialization comparison: whitespace between array values and ordering of object member serialization are not significant.
Duplicate "op" member names in an operation object (as shown in Appendix A.13) cannot be reliably handled because JSON's uniqueness requirement for object member names is only a SHOULD, and no standard error handling for duplicates exists.
JSON object member ordering is not significant; therefore operation objects with the same members in different orders are equivalent (e.g., {"op":"add","path":"/a","value":"foo"} equals {"value":"foo","path":"/a","op":"add"}).
When used with the HTTP PATCH method, JSON Patch inherits HTTP PATCH's atomicity requirement (RFC 5789 Section 2.2). A failed "test" operation causes the entire patch — including prior operations in the sequence — to be rolled back.
For the "add" operation targeting an array, the specified index MUST NOT be greater than the number of elements in the array. The "-" token appends to the end.
For the "move" operation, the "from" location MUST NOT be a proper prefix of the "path" location; a location cannot be moved into one of its children.
If any normative requirement is violated or any operation is unsuccessful, evaluation of the JSON Patch document SHOULD terminate and the entire patch SHALL NOT be deemed successful (atomic all-or-nothing semantics).
Members not explicitly defined for an operation MUST be ignored; the operation completes as if the undefined member did not appear.
Operation objects MUST have exactly one "op" member whose value MUST be one of "add", "remove", "replace", "move", "copy", or "test"; other values are errors.
Operation objects MUST have exactly one "path" member whose value is a JSON Pointer (RFC 6901) string referencing the target location within the document.
A JSON Patch document is a JSON array of operation objects. Each object represents a single operation to be applied sequentially to the target JSON document. Evaluation continues until all operations succeed or an error is encountered.
The "add" operation inserts a value at an array index, adds a new object member if absent, or replaces an existing member's value. The operation object MUST contain a "value" member specifying the value to add.
The "copy" operation copies the value at the "from" location to the target location. The operation object MUST contain a "from" member (a JSON Pointer string), and the "from" location MUST exist.
The "move" operation removes the value at the "from" location and adds it to the target location. The operation object MUST contain a "from" member (a JSON Pointer string), and the "from" location MUST exist.
The "remove" operation removes the value at the target location. The target location MUST exist; removing an array element shifts higher-index elements one position left.
The "replace" operation replaces the value at the target location with a new value specified in the required "value" member. The target location MUST exist and is functionally equivalent to remove followed by add.
The "test" operation tests that the value at the target location equals a specified "value" member. Equality is type-aware: strings compare code-point-by-code-point, numbers compare numerically, arrays and objects compare recursively, and literals compare by identity.
This document registers the "application/json-patch+json" media type with IANA for identifying JSON Patch documents. File extension is ".json-patch"; encoding is binary; change controller is IETF.
JSON Patch inherits the security considerations of JSON (RFC 4627) and JSON Pointer (RFC 6901). Additionally, some older browsers can be coerced into loading a JSON array as a script, exposing a JSON Patch document containing sensitive information via a Cross-Site Request Forgery (CSRF) attack.
Publishers concerned about CSRF exposure of JSON Patch documents (whose root is an array) are advised to avoid serving such documents via HTTP GET, since older browsers (estimated <1% market share at time of writing) can be coerced into fetching them cross-origin.