106 lines
3.9 KiB
Markdown
106 lines
3.9 KiB
Markdown
|
---
|
|||
|
|
obj: concept
|
|||
|
|
website: https://jsonpatch.com
|
|||
|
|
rfc: https://datatracker.ietf.org/doc/html/rfc6902
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# JSONPatch
|
|||
|
|
JSON Patch is a format for describing changes to a [JSON](../files/JSON.md) document. It can be used to avoid sending a whole document when only a part has changed. When used in combination with the [HTTP](../internet/HTTP.md) PATCH method, it allows partial updates for [HTTP](../internet/HTTP.md) APIs in a standards compliant way.
|
|||
|
|
|
|||
|
|
The patch documents are themselves [JSON](../files/JSON.md) documents.
|
|||
|
|
A JSON Patch document is just a [JSON](../files/JSON.md) file containing an array of patch operations. The patch operations supported by JSON Patch 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.
|
|||
|
|
|
|||
|
|
## Simple example
|
|||
|
|
### The original document
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"baz": "qux",
|
|||
|
|
"foo": "bar"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### The patch
|
|||
|
|
```json
|
|||
|
|
[
|
|||
|
|
{ "op": "replace", "path": "/baz", "value": "boo" },
|
|||
|
|
{ "op": "add", "path": "/hello", "value": ["world"] },
|
|||
|
|
{ "op": "remove", "path": "/foo" }
|
|||
|
|
]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### The result
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"baz": "boo",
|
|||
|
|
"hello": ["world"]
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## JSON Pointer
|
|||
|
|
JSON Pointer ([IETF RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901/)) defines a string format for identifying a specific value within a [JSON](../files/JSON.md) 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 separated by `/` characters, these tokens either specify keys in objects or indexes into arrays. For example, given the [JSON](../files/JSON.md)
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"biscuits": [
|
|||
|
|
{ "name": "Digestive" },
|
|||
|
|
{ "name": "Choco Leibniz" }
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
`/biscuits` would point to the array of biscuits and `/biscuits/1/name` would point to `"Choco Leibniz"`.
|
|||
|
|
|
|||
|
|
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](../files/JSON.md)).
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
## Operations
|
|||
|
|
### Add
|
|||
|
|
```json
|
|||
|
|
{ "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.
|
|||
|
|
|
|||
|
|
### Remove
|
|||
|
|
```json
|
|||
|
|
{ "op": "remove", "path": "/biscuits" }
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Removes a value from an object or array.
|
|||
|
|
```json
|
|||
|
|
{ "op": "remove", "path": "/biscuits/0" }
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Removes the first element of the array at `biscuits` (or just removes the “0” key if `biscuits` is an object)
|
|||
|
|
|
|||
|
|
### Replace
|
|||
|
|
```json
|
|||
|
|
{ "op": "replace", "path": "/biscuits/0/name", "value": "Chocolate Digestive" }
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Replaces a value. Equivalent to a "remove" followed by an "add".
|
|||
|
|
|
|||
|
|
### Copy
|
|||
|
|
```json
|
|||
|
|
{ "op": "copy", "from": "/biscuits/0", "path": "/best_biscuit" }
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Copies a value from one location to another within the [JSON](../files/JSON.md) document. Both `from` and `path` are JSON Pointers.
|
|||
|
|
|
|||
|
|
### Move
|
|||
|
|
```json
|
|||
|
|
{ "op": "move", "from": "/biscuits", "path": "/cookies" }
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Moves a value from one location to the other. Both `from` and `path` are JSON Pointers.
|
|||
|
|
|
|||
|
|
### Test
|
|||
|
|
```json
|
|||
|
|
{ "op": "test", "path": "/best_biscuit/name", "value": "Choco Leibniz" }
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Tests that the specified value is set in the document. If the test fails, then the patch as a whole should not apply.
|