JSON merge vs JSON patch

November 1, 2026 · 14 min read

Full PUT replacements waste bandwidth and race concurrent edits. JSON Merge Patch (RFC 7396) and JSON Patch (RFC 6902) standardize partial updates with different ergonomics. Picking the wrong one shows up as arrays replaced when developers meant to append, or null wiping fields unexpectedly.

Why partial JSON updates exist

Clients send a delta; servers apply it to a resource document. REST APIs advertise support via Content-Type: application/merge-patch+json or application/json-patch+json. Idempotency and optimistic locking (ETags) still matter - patches are not a substitute for concurrency control.

JSON Merge Patch (RFC 7396)

Merge Patch is a JSON object whose keys mirror the resource. Values replace fields; nested objects merge recursively. A null value means delete the key if present. Arrays replace entirely - there is no per-index merge in RFC 7396.

// Original: { "name": "Ada", "tags": ["go"], "meta": { "a": 1 } }
// Merge patch: { "meta": { "b": 2 }, "tags": ["go", "rust"] }
// Result meta merges; tags replaced as a whole

JSON Patch (RFC 6902)

Patch is an array of operations: add, remove, replace, move, copy, test. Paths use JSON Pointer. test enables compare-and-set - if the value at a path differs, the patch aborts. Fine for ordered array edits and surgical changes.

[
  { "op": "test", "path": "/version", "value": 3 },
  { "op": "replace", "path": "/status", "value": "shipped" }
]

Merge vs patch: which to choose

Merge Patch - simpler clients, shallow resources, OK with full array replacement.
JSON Patch - precise array edits, atomic test operations, audit logs of operations.
Avoid mixing both on the same endpoint without clear documentation.

Testing document changes

After applying patches in unit tests, diff golden files with JSON compare to see unexpected path changes. Merge Patch surprises often involve null deleting nested keys - assert final trees, not just HTTP 200.

FAQ

Does merge patch delete keys with null?: Yes - null deletes the member if it exists at that path; nested null inside objects deletes nested keys.
Can JSON Patch add to arrays?: Yes with add and path /items/- for append, or /items/2 for insert with index.
Which does OpenAPI prefer?: OpenAPI 3 describes both; pick one per resource and document Content-Type.

Browse all tools