How-To
How to Apply a JSON Patch
You already have an RFC 6902 patch - from an API, a colleague, or a generator - and want to execute it against a JSON document. Here is what applying means, how to do it safely, and the same operation in the browser, JavaScript and Python.
Applying a JSON Patch means executing its operations in order against the target document. Each operation sees the result of the previous one, and evaluation stops at the first operation that fails. Paste the document and the patch into the apply tool to see the result instantly.
A minimal example
Patch
[
{ "op": "replace", "path": "/age", "value": 31 },
{ "op": "add", "path": "/active", "value": true }
]Before
{
"name": "Alice",
"age": 30
}After
{
"name": "Alice",
"age": 31,
"active": true
}The semantics that matter
- Sequential. Operations run top to bottom. A path that is valid when you wrote the patch can be invalid by the time its operation runs - array indexes especially (see index shifting).
- Stop on first error. Per RFC 6902, evaluation terminates with an error as soon as one operation fails. Whether the earlier operations are rolled back is up to the library - many build the result separately, but do not rely on it without checking.
- Exact paths. Every
pathandfromis a JSON Pointer: keys match exactly, array indexes are zero-based.
Validate before you apply
Two habits prevent almost every bad application:
1. Guard assumptions with test. A test operation at the top of the patch fails the whole thing when the document is not in the state you expect - optimistic concurrency for free:
Patch
[
{ "op": "test", "path": "/age", "value": 30 },
{ "op": "replace", "path": "/age", "value": 31 }
]2. Dry-run on a copy. The verify mode in this tool applies the patch and checks the result against your expected document, with human-readable errors when an operation fails. For failures and their fixes, see JSON Patch errors.
Applying in code
JavaScript (fast-json-patch)
import { applyPatch } from 'fast-json-patch';
const result = applyPatch(document, patch).newDocument;Python (jsonpatch)
import jsonpatch result = jsonpatch.apply_patch(document, patch)
More detail in the language guides: JSON Patch in JavaScript and JSON Patch in Python.
Common mistakes
Applying a patch you have not validated
A patch is code: it can delete data. Run it against a copy first, or open it in the apply tool and inspect the result before it touches production data.
Assuming a failed patch changed nothing
The RFC stops evaluation at the first failed operation, but whether earlier operations roll back depends on the library. If all-or-nothing matters to you, put a test operation first or apply to a copy.
Feeding the patch itself as the target document
A classic copy-paste bug: the target is the document you want to change, the patch is the array of operations. Applying a patch to itself fails immediately.
Ignoring type mismatches in test operations
test compares exactly: 1 and "1" are different values. A test that "should pass" and does not is usually a string-versus-number issue.
Reference
Operation semantics are in RFC 6902, section 4, and the error-termination rule in section 5.
Apply this patch yourself
Open the apply tool with the document and patch above preloaded - edit the patch and watch the result update.
Open the apply tool with this example