JSON Patch vs JSON Merge Patch

JSON Patch is an operation list

JSON Patch uses a JSON array of add, remove, replace, move, copy and test operations. Each operation targets a JSON Pointer path. Because operations are ordered, an earlier array change can affect the path used by a later operation.

The test operation supports optimistic concurrency at the document level: a patch can assert an expected value before changing it. Servers must still apply authorization and business validation to every affected path.

[
  { "op": "test", "path": "/status", "value": "draft" },
  { "op": "replace", "path": "/status", "value": "published" }
]

Merge Patch looks like the target document

JSON Merge Patch sends an object containing the members to add or replace. A null member means remove that member from the target. Values not mentioned remain unchanged. This shape is easy to read for ordinary object updates.

Arrays are replaced as whole values rather than edited by index. Merge Patch is therefore concise for profile-like resources but less precise for long arrays or ordered collections.

{
  "displayName": "Avery",
  "legacyField": null
}

Null is the key tradeoff

In Merge Patch, null carries deletion semantics. That makes it awkward when null is a meaningful value that must be stored explicitly. JSON Patch can replace a member with null or remove it as two distinct operations.

Document your API media type and semantics instead of accepting a generic application/json body and calling it a patch. JSON Patch commonly uses application/json-patch+json; Merge Patch uses application/merge-patch+json.

Choose based on client intent

Use JSON Patch when clients need exact path operations, guarded changes or targeted array edits. Use Merge Patch when clients mainly update object properties and a document-shaped request is easier to produce and review.

Whichever format you choose, validate paths, restrict immutable fields, enforce authorization after resolving the operation and return clear errors. A standards-compliant patch can still request a change the caller is not allowed to make.