Encrypt Online
Theme

Data Formats & Debugging · Field note

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.

Encrypt Online Editorial Team3 min read
JSON Patch for partial updates: add, replace, remove, move, copy, and test guide cover

Before you start

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.

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.

Watch for: 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 test when 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.

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.

JSON
[
  { "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 path before assuming the operation type is wrong.
  • Use test to make assumptions explicit when patching important documents.

Common questions

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.

References

Report a correction