JSON Patch for partial updates: add, replace, remove, move, copy, and test
Learn how JSON Patch operations behave in practice so partial updates feel predictable instead of risky.
Tip
Lint or format before comparing data, then check that cleanup did not change the fields, order, or values that matter.
JSON Patch is powerful because it lets you describe a change instead of resending a whole document. It is risky when people treat the patch as obvious instead of inspecting exactly what each operation will touch.
The best way to teach patching is operation by operation, with the original document still visible.
Summary
Definition: JSON Patch is a JSON document format for expressing a sequence of operations against a target JSON document.
Why it matters: It makes partial updates explicit, reviewable, and interoperable when the exact path behavior is understood.
Pitfall: Patch operations are applied in order. One wrong path or array index can make later operations fail or target the wrong place.
Every operation has a different expectation
add can create or insert, replace requires the target to exist, remove deletes, move relocates, copy duplicates, and test asserts a value before proceeding. Lumping them together causes the usual confusion: people expect replace to behave like add, or they forget that test can deliberately fail a patch sequence.
This is why a patch tester should show operations one by one, not just the final result.
Array paths deserve extra respect
Array indexes are positional, so earlier operations can change what later indexes refer to. That is not a bug in JSON Patch. It is part of the model. The safest way to reason about patches is to read them in order against the document state after each step.
Once people see that progression, patches stop feeling magical and start feeling reviewable.
- Use
testwhen a patch depends on current state. - Read array operations sequentially; earlier edits change later positions.
- Resolve every pointer before assuming the operation is wrong.
Patch review is a product feature
For this workflow, the product opportunity is not just “apply patch.” It is “show me the before, the operation trace, and the after.” That makes the tool useful in debugging, not merely in transformation.
Quick example
Use this when you want a tiny patch that adds a field and then verifies it.
What to notice: The test operation is not decoration. It can protect later steps by asserting the document is in the state you expect.
[
{ "op": "add", "path": "/status", "value": "active" },
{ "op": "test", "path": "/status", "value": "active" }
]
Practical check
- Read patch operations in order, not as if they apply simultaneously.
- Resolve the
pathbefore assuming the operation type is wrong. - Use
testto make assumptions explicit when patching important documents.
FAQ
Can replace create a new key?
No. replace expects the target to exist; add is the operation that can create or insert.
Why did an array patch hit the wrong element?
Because earlier operations changed the positions before later indexes were applied.
Developer workflow
Use this guide as a debugging pass before you paste structured data into an API, config file, or migration script.
- Keep one raw copy of the payload before any formatter touches it.
- Lint or format first, then compare important fields and ordering before converting.
- Save the final clean payload separately from notes, comments, and temporary examples.
1. raw payload
2. lint/format without changing meaning
3. compare fields and ordering
4. convert only after validation passes