JSON Patch vs JSON Merge Patch

The problem

Developers often send one format to an endpoint that expects the other, or assume arrays behave the same way in both. JSON Patch describes precise add/remove/replace/move/copy/test operations. JSON Merge Patch is a simpler object where present keys overwrite, and null deletes a field.

The biggest gotcha is arrays: Merge Patch replaces an array wholesale, while JSON Patch can target an individual index.

Sample input

{
  "name": "Asha",
  "email": "asha@example.com",
  "roles": ["user", "editor"]
}

[
  { "op": "replace", "path": "/email", "value": "new@example.com" },
  { "op": "remove", "path": "/roles/1" }
]

{
  "email": "new@example.com",
  "roles": ["user"]
}

Expected output

{
  "name": "Asha",
  "email": "new@example.com",
  "roles": ["user"]
}

JSON Patch removes the single role at index 1. JSON Merge Patch replaces the entire roles array with ["user"]. They reach the same result here, but the array semantics differ.

How to do it

1. Use JSON Patch when you need precise, ordered operations or array-element edits.
2. Use JSON Merge Patch when a small partial object is enough and you replace whole arrays.
3. Remember that in Merge Patch a null value deletes the key.
4. Match the Content-Type to the format your API expects.
5. Apply the change locally first to confirm the result before sending it.

Common mistakes

• Sending a JSON Patch array to an endpoint that expects Merge Patch.
• Expecting Merge Patch to remove a single array element — it replaces the whole array.
• Forgetting that null means “delete this field” in Merge Patch.
• Using the wrong Content-Type header for the body you send.

Related tools

• Diff two JSON documents
• Validate JSON against a schema

Related guides

• Generate JSON Patch from two JSON files
• Apply JSON Patch online

FAQ

Compare both formats side by side locally in your browser. Nothing is uploaded.