Data Formats & Debugging
JSON Patch Explained
Learn JSON Patch add, replace, remove, move, copy and test operations with examples of paths, array indexes and failed updates.
JSON Patch sends a list of changes to a document. Check each operation's path and value before applying it, especially when earlier operations change array indexes.
The best way to teach patching is operation by operation, with the original document still visible.
In brief
What it is: 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.
Worth knowing: 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.
A patch tester should show each operation and the final result.
Array paths deserve extra respect
Array indexes are positional, so earlier operations can change what later indexes refer to. This behavior is part of the JSON Patch model. Read operations in order against the document state produced by each preceding 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
A patch tester shows the original document, each operation, and the resulting document.
See it in a small example
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" }
]
What to verify
- 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.
Common questions
Can replace create a new key?
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.
