Guide

JSON Patch vs JSON Merge Patch

RFC 6902 and RFC 7396 both describe how to update a JSON document with an HTTP PATCH request, but they work very differently. Here is how to choose.

The one-minute version

JSON Patch (RFC 6902) is a list of explicit operations - add, remove, replace, move, copy, test - applied in order. JSON Merge Patch (RFC 7396) is a partial copy of the target document: keys you send replace the old values, and null deletes a key. Merge Patch is simpler to write by hand; JSON Patch is more precise and the only one of the two that can target individual array elements.

Side by side

Same change - bump a version, add a tag, delete a field - in both formats:

// Original document
{ "name": "demo", "version": 1, "tags": ["a", "b"] }

// JSON Patch (RFC 6902) - media type application/json-patch+json
[
  { "op": "replace", "path": "/version", "value": 2 },
  { "op": "add", "path": "/tags/-", "value": "c" },
  { "op": "remove", "path": "/name" }
]

// JSON Merge Patch (RFC 7396) - media type application/merge-patch+json
{ "version": 2, "tags": ["a", "b", "c"], "name": null }

Both produce { "version": 2, "tags": ["a", "b", "c"] } - but look at what Merge Patch needed for the array: the entire new array. JSON Patch appended one element; Merge Patch had to replace the whole value.

Where JSON Patch wins

• Array surgery. Insert, remove, or reorder individual array elements without resending the whole array. Merge Patch can only replace arrays wholesale.
• Optimistic concurrency. The test operation fails the patch if the document is not in the expected state - a built-in conflict guard.
• Ordered evaluation. Operations run in sequence and stop at the first error; rollback depends on the implementation.
• Auditability. An operation list reads like a changelog, which is why tools like Kubernetes use it.

Where Merge Patch wins

• Simplicity. If you can write the resource, you can write the patch - it is just a partial document. Great for flat objects and hand-written API calls.
• Small payloads for shallow updates. Changing three top-level fields takes three key-value pairs instead of three operation objects.

The null trap

Merge Patch deletes keys with null - which means you cannot set a key to an actual JSON null. If your data model uses null as a meaningful value, Merge Patch cannot express it. JSON Patch distinguishes replace with a null value from remove cleanly:

[
  { "op": "replace", "path": "/middleName", "value": null },
  { "op": "remove", "path": "/nickname" }
]

Which should your API use?

For most resource APIs, supporting both is common: accept application/merge-patch+json for convenience and application/json-patch+json for precision. If you can only pick one, choose JSON Patch when arrays, concurrency control, or meaningful nulls matter - and Merge Patch when your documents are flat and your clients write patches by hand.

See the difference yourself

Paste two documents into the JSON Patch Generator and look at the RFC 6902 operations it produces - then imagine expressing the same change as a Merge Patch. The JSON Diff tool shows the raw line-level changes underneath both formats.

Go deeper: JSON Patch documentation, examples, and the test operation that makes JSON Patch safe for concurrent updates.