JSON Patch vs Merge Patch vs Text Diff

JSON Patch lists exact operations such as add, remove, replace, move, copy, and test. JSON Merge Patch sends the object shape you want to change, with null meaning deletion. Use text diff for review, JSON Patch for precise API updates, and Merge Patch for simple object updates.

Those three methods answer different questions. A text diff asks what characters changed. A patch document tells an API how to change stored JSON. Choosing by name alone can produce broken array updates, accidental deletions, or noisy reviews.

JSON Patch vs Merge Patch vs Text Diff

One Update Expressed Three Ways

We tested a billing settings object. The plan changes from starter to team. The project limit rises from three to ten. One feature joins an existing array.

{
  "plan": "starter",
  "limits": {
    "projects": 3,
    "storageGb": 10
  },
  "features": ["diff", "export"],
  "supportEmail": null
}

The updated object keeps the storage limit and support email unchanged:

{
  "plan": "team",
  "limits": {
    "projects": 10,
    "storageGb": 10
  },
  "features": ["diff", "export", "audit-log"],
  "supportEmail": null
}

A side-by-side text comparison makes the review fast. It highlights the changed strings, number, and array item. It also keeps the unchanged context visible. In our run, the tool measured 88.61% similarity.

That score describes the text, not the business impact. A one-character price or permission change can matter greatly. Never use similarity percentage as an approval rule.

How JSON Patch Represents the Update

RFC 6902 defines JSON Patch as an ordered array of operations. Each operation names a path using JSON Pointer syntax.

[
  { "op": "test", "path": "/plan", "value": "starter" },
  { "op": "replace", "path": "/plan", "value": "team" },
  { "op": "replace", "path": "/limits/projects", "value": 10 },
  { "op": "add", "path": "/features/-", "value": "audit-log" }
]

The operations run in order. If one fails, later operations should not run. Here, test checks the expected plan before anything changes. It helps prevent a stale client from silently overwriting a newer plan.

JSON Patch supports six operations: add, remove, replace, move, copy, and test. This vocabulary makes intent explicit. It also means clients must build correct paths and handle failures.

Why arrays favor JSON Patch

The path /features/- appends a value to the array. A numeric path can target an existing position. This precision reduces payload size when arrays are large.

Array indexes can still be fragile during concurrent edits. If another request inserts item zero first, later indexes shift. Use resource versions, ETags, or a careful test before index-based changes.

How JSON Merge Patch Represents the Update

RFC 7396 defines JSON Merge Patch. Its document looks like the resource fragment you want to change.

{
  "plan": "team",
  "limits": {
    "projects": 10
  },
  "features": ["diff", "export", "audit-log"]
}

This patch is shorter and easier to read. The missing storageGb member remains unchanged because its parent patch is an object. The entire features array is replaced, however. Merge Patch cannot append one array item by position.

The null problem

In Merge Patch, "supportEmail": null means remove that member. It does not mean store a JSON null as the new value. That rule makes Merge Patch awkward when null carries real business meaning.

JSON Patch avoids that ambiguity. A replace operation can set a value to null. A separate remove operation deletes the member.

What Text Diff Shows That Patches Do Not

A patch is an instruction. A text diff is evidence for a reviewer. It can reveal indentation changes, reordered keys, changed escaping, or an unexpected newline. Those details may disappear from a semantic patch.

JSON objects are unordered collections according to RFC 8259. Reordering keys should not change their meaning. A text diff will still highlight the reordered lines.

That behavior is useful when formatting matters to your repository. It becomes noise when comparing API payloads. For cleaner review, format both documents consistently before running the comparison. Our guide to why JSON diffs are hard covers key order, types, and nesting.

Four Mistakes That Break Real Updates

1. Treating JSON Pointer paths like file paths

JSON Patch paths follow JSON Pointer rules, not operating-system path rules. A slash separates object members, while special characters need escaping. Use ~1 for a literal slash and ~0 for a tilde.

For example, the key billing/email uses the path /billing~1email. Sending /billing/email targets a nested member instead. Tests should cover keys containing both special characters.

2. Assuming replace will create a missing member

A JSON Patch replace target must already exist. Use add when a member may be absent. Servers should return a clear error instead of guessing the client's intent.

3. Sending only one changed array item with Merge Patch

Merge Patch does not merge array elements by index or identifier. The supplied array replaces the stored array. A partial-looking array can therefore discard values that another client added.

4. Generating patches from invalid or duplicate-key JSON

JSON object names should be unique for predictable behavior. Parsers handle duplicates differently, often keeping either the first or last value. Validate both documents before generating any machine-applied change.

Text comparison remains useful during this validation step. It can expose the duplicate line even when a parser silently drops one value. Review the raw text first, then patch the validated structure.

Which Method Should You Choose?

• Choose JSON Patch when individual array items need updates or removals.
• Choose JSON Patch when the request must verify an expected value first.
• Choose Merge Patch for simple partial updates to object-heavy resources.
• Avoid Merge Patch when stored null and deleted are different states.
• Choose text diff when a person must review two complete versions.
• Use both when an API patch also needs a human approval trail.

The HTTP method alone does not settle the choice. An endpoint using PATCH must document which patch format it accepts. Send the matching media type and validate it on the server.

A Safer Review Workflow

1. Validate both JSON documents before comparing them.
2. Format both with the same indentation and key-order policy.
3. Review the complete before-and-after text side by side.
4. Generate the chosen patch from validated application data.
5. Apply it to a copy, then compare the result with the target.
6. Use an ETag, version field, or test operation for concurrent writes.

This loop catches two different failure classes. The text review finds surprising content. The apply-and-compare step finds an incorrect patch. Neither check fully replaces the other.

Frequently Asked Questions

Is JSON Patch the same as a JSON diff?

No. JSON Patch is a standardized list of update operations. A JSON diff is any report describing differences between documents. Some diff tools can generate JSON Patch, but many only display changes.

When should I use JSON Merge Patch?

Use it for straightforward partial updates to objects. It works well when arrays are small, null does not represent stored data, and clients benefit from a compact object-shaped request.

How do I delete a value with Merge Patch?

Set the member to null in the patch. The server removes that member. Because null means deletion, Merge Patch cannot clearly express storing an explicit null there.

Can JSON Patch update one array item?

Yes. Use a numeric JSON Pointer segment for an existing position. Use - with add to append. Protect index-based writes against concurrent array changes.

Does JSON key order matter?

Object member order does not change JSON meaning. A text diff can still show reordered keys because it compares characters and lines. Normalize key order when those changes create noise.

Review Other File Changes

Text comparison works best for JSON source and API examples. For document pages, use PDF Compare. For values, formulas, and rows, use Excel Compare. Different structures need different review views.

Sources

• RFC 6902: JavaScript Object Notation (JSON) Patch
• RFC 7396: JSON Merge Patch
• RFC 8259: The JavaScript Object Notation Data Interchange Format