What JSON Patch is
JSON Patch (RFC 6902) is a list of operations that turn one JSON document into another. Each operation has an op and a path. The path is a JSON Pointer (RFC 6901): a slash-separated walk from the root. The six operations are add, remove, replace, move, copy, and test.
The list is ordered. Later operations see the document after earlier ones. test does not change the document. It checks that a location currently holds an expected value, which is how an API can reject a patch when someone else already edited that field.
This page applies the patch in your browser. The document and the patch are not uploaded.
How a pointer addresses a value
An empty pointer, "", means the whole document. "/name" is the name member. "/tags/0" is the first array element, counting from zero. "/tags/-" in an add operation means append. A "~" inside a key is written "~0", and a "/" inside a key is written "~1". Decode "~1" before "~0", which is what this page does, so a literal "~1" in a key survives.
{ "op": "add", "path": "/a~1b", "value": 1 }
{ "op": "remove", "path": "/c~0d" }A worked patch
Start with the document below. test checks that name is still Ada. replace renames it. add with "/tags/-" appends snowflake, so the array is ["ulid", "uuid", "snowflake"]. add creates address.country. remove of "/tags/0" then drops ulid, because indexes refer to the array as it is at that step. The result is the third block.
{
"name": "Ada",
"tags": ["ulid", "uuid"],
"address": { "city": "Hanoi" }
}[
{ "op": "test", "path": "/name", "value": "Ada" },
{ "op": "replace", "path": "/name", "value": "Ada Lovelace" },
{ "op": "add", "path": "/tags/-", "value": "snowflake" },
{ "op": "add", "path": "/address/country", "value": "VN" },
{ "op": "remove", "path": "/tags/0" }
]{
"name": "Ada Lovelace",
"tags": ["uuid", "snowflake"],
"address": { "city": "Hanoi", "country": "VN" }
}move, copy, and test
move removes the value at from and adds it at path. copy does the add without the remove, so the source stays. A move of an array element onto a later index in the same array is easy to get wrong, because the removal shifts everything after it. test compares the current value with value. If it does not match, this page stops with an error and does not pretend the rest of the list was applied. RFC 6902 expects the whole patch to fail when any operation fails. Callers should treat the result as all-or-nothing.
When to use it
- You are writing a partial update and want to see the document after a real op list, not after a mental diff.
- You need a precondition. Put test first so a stale client cannot overwrite a field that changed.
- You are choosing between JSON Patch and JSON Merge Patch (RFC 7396). Merge Patch is one document: objects merge, arrays are replaced wholesale, and null deletes a member. It cannot append to an array or express test.
Pitfalls
- Array indexes move. Removing /tags/0 and then removing /tags/1 does not remove the original first and second items. After the first removal, the old second item is at index 0.
- replace requires the path to exist. add creates a missing object member, and add with "-" appends. Using replace for a new field fails.
- RFC 6902 paths are case-sensitive. This page has an Ignore Case option, and it starts on. That can hide a wrong key. Turn it off when you want the spec.
- Strict Path Validation is a local option, not part of the RFC. Leave it on when you want a missing intermediate object to be an error instead of something the add walks through.
- A patch is not a diff format you can reorder. move and remove depend on earlier steps. Generate the list from a before and after if you do not want to maintain it by hand.
JSON Patch and the nearby formats
| Format | What you send | What it cannot do |
|---|---|---|
| JSON Patch (RFC 6902) | An ordered list of op objects | Nothing implicit: every change is an operation |
| JSON Merge Patch (RFC 7396) | A partial document | Append to an array, or test a precondition. null means delete |
| A JSON diff view | Two full documents | It shows a change. It is not a document you POST unless you turn it into a patch |
Questions
What does /tags/- mean?
In an add operation, the single character - as the last pointer token appends to the array. It is not a member named "-". On any other operation, - is not a special index.
Why did remove delete the wrong array item?
Each operation sees the document left by the previous one. After a removal, later indexes point at different elements. Remove higher indexes first, or rebuild the patch from the updated document.
How do I name a key that contains a slash?
Escape it. / in a key becomes ~1, and ~ in a key becomes ~0. The pointer /a~1b refers to the member a/b. /c~0d refers to the member c~d.
Does test roll back earlier operations?
On a correct server, a failed test rejects the whole patch, including operations that appear before it. Do not assume a client can keep a half-applied document. Put test operations at the points where the precondition must hold.
Is Ignore Case part of RFC 6902?
No. JSON Pointer member names are exact. Ignore Case is a switch on this page and it is on by default. Turn it off to match the specification.