| title |
|---|
JSONPatch |
JSON Patch is a format for describing changes to a JSON document. It can be used to avoid sending a whole document when only a part has changed. When used in combination with the HTTP PATCH method it allows partial updates for HTTP APIs in a standards compliant way.
The patch documents are themselves JSON documents.
JSON Patch is specified in RFC 6902 from the IETF.
{
"baz": "qux",
"foo": "bar"
}
[
{ "op": "replace", "path": "/baz", "value": "boo" },
{ "op": "add", "path": "/hello", "value": ["world"] },
{ "op": "remove", "path": "/foo"}
]
{
"baz": "boo",
"hello": ["world"]
}
A JSON Patch document is just a JSON file containing an array of patch operations. The patch operations supported by JSONPatch are "add", "remove", "replace", "move", "copy" and "test". The operations are applied in order; if any of them fail then the whole patch operation should abort.
JSON Pointer (IETF RFC 6901) defines a string format for identifying a specific value within a JSON document. It is used by all operations in JSON Patch to specify the part of the document to operate on.
A JSON Pointer is a string of tokens seperated by / characters, these tokens either specify keys in objects or indexes into arrays. For example, given the JSON
{
"biscuits": [
{"name":"Digestive"},
{"name": "Choco Liebniz"}
]
}
/biscuits would point to the array of biscuits and /biscuits/1/name would point to "Choco Liebniz".
To point to the root of the document use an empty string for the pointer. The pointer / doesn't point to the root, it points to a key of "" on the root (which is totally valid in JSON).
If you need to refer to a key with ~ or / in its name you must escape the characters with ~0 and ~1 respectively. For example, to get "baz" from {"foo/bar~": "baz"} you'd use the pointer /foo~1bar~0.
Finally, if you need to refer to the end of an array you can use - instead of an index. For example, to refer to the end of the array of biscuits above you would use /biscuits/-. This is useful when you need to insert a value at the end of an array.
{"op": "add", "path": "/biscuits/1", "value": {"name": "Ginger Nut"}}
Adds a value to an object or inserts it into an array. In the case of an array the value is inserted before the given index. The - character can be used instead of an index to insert at the end of an array.
{"op": "remove", "path": "/biscuits"}
Removes a value from an object or array.
{"op": "replace", "path": "/biscuits/0/name", "value": "Chocolate Digestive"}
Replaces a value. Equivalent to a "remove" followed by an "add".
{"op": "copy", "from": "/biscuits/0", "path": "/best_biscuit"}
Copy a value from one location to another within the JSON document. Both from and path are JSON Pointers.
{"op": "move", "from": "/biscuits", "path": "/cookies"}
Move a value from one location to the other. Both from and path are JSON Pointers.
{"op": "test", "path": "/best_biscuit/name", "value": "Choco Liebniz"}
Tests that the specified value is set in the document. If the test fails then the patch as a whole should not apply.
Libraries are available for a range of languages currently. You should check that the library you wish to use supports the RFC version of JSON Patch as there have been changes from the earlier draft versions and at the time of writing not all libraries have been updated.
If we're missing a library please let us know (see below)!
- Ramone (a framework for consuming REST services, includes a JSONPatch implementation)
- JsonPatch (Adds JSONPatch support to ASP.NET Web API)
A collection of conformance tests for JSON Patch are maintained on Github:
github.com/json-patch/json-patch-tests
JSON Schema is a way to describe JSON data formats like JSONPatch. Supporting tools and libraries can use these schemas to provide auto-completion, validation and tooltips to help JSON file authors.
http://json.schemastore.org/json-patch
jsonpatch.com is hosted on Github. Pull Requests are welcome: