PDFFlare
8 min read

How to Apply a JSON Merge Patch (RFC 7396) — Complete Guide

Need to apply a JSON Merge Patch to a document? Here's how RFC 7396 works in practice. Your service exposes a PATCH endpoint with application/merge-patch+json. A client sends a small delta, you apply it to the stored document, you save the result. Sometimes a field shows up missing from the result and you can't see why. The bug is almost always a misread of one of RFC 7396's three rules.

In this guide you'll learn how to apply a JSON Merge Patch using PDFFlare's JSON Merge Patch tool — the three rules of RFC 7396, why null behaves surprisingly, when to reach for JSON Patch (RFC 6902) instead, and how to dry-run a patch in your browser before sending it over the wire.

The Three Rules of RFC 7396

JSON Merge Patch is deliberately small. The whole spec fits in three rules:

  1. If the patch isn't a JSON object, the result is just the patch (the target is replaced).
  2. For each key in the patch object: null deletes the key from the target. Anything else becomes the new value (recursing into nested objects).
  3. Keys not present in the patch are left alone. The target keeps its existing value for any field the patch doesn't touch.

How to Apply a Merge Patch (Step by Step)

  1. Open PDFFlare's JSON Merge Patch tool.
  2. Paste your target JSON. The current state of the document — a config, a resource, anything.
  3. Paste the merge patch. The delta the client sent (or the delta you computed).
  4. Click Apply Patch. The result pane shows the patched document. Review before sending.
  5. Copy and ship. Or paste back into the source-of- truth and re-run the patch process to verify idempotency.

Merge Patch vs JSON Patch (RFC 6902)

Two specs, two tools:

  • Merge Patch (RFC 7396):a single document mirroring the target's shape. Easy to read; can't express element-level array operations or set a key to null.
  • JSON Patch (RFC 6902): an array of explicit operations (add, remove, replace, move, copy, test). Verbose; can do anything.

Use Merge Patch for HTTP PATCH on document-shaped resources where the natural representation of changes is "the new shape". Use JSON Patch when you need precise array operations or you must preserve actual null values.

Real Use Cases

HTTP PATCH endpoints

Many APIs accept the application/merge-patch+json content type. Compute the patch on the client, send only what changed, server applies it.

Config-update workflows

Helm or Kustomize-style overlays — base config plus a delta override. Resolving the delta against the base before deploying gives you a single canonical document to inspect.

Edit-then-save UIs

The UI computes a delta from the original; the server applies the delta to the stored value. Less wire data, fewer last-write-wins conflicts.

Common Mistakes (and How to Avoid Them)

  • Trying to set a value to null.You can't with Merge Patch — null deletes. Use JSON Patch (RFC 6902) if null is a legitimate value in your data.
  • Expecting array merges. Arrays in the patch replace arrays in the target wholesale. For element-level array edits, JSON Patch is the right spec.
  • Forgetting that nested objects recurse. Send a patch like {"address": {"zip": "10002"}}and the address's other fields stay intact. Send {"address": null} and the entire address goes away.

Privacy: Your JSON Stays Local

Both the target and the patch are processed in your browser. Safe for production payloads and internal API contracts.

Related Workflows in the JSON Suite

Adjacent tools you might find useful while working on the same JSON document: the JSON Diff and JSON Formatter both pair well with the conversion above. The first handles a different output format that consumers of your data may prefer; the second covers the validation side of the same workflow.

Related Tools

  • JSON Diff — see what changed structurally between two documents.
  • JSON Schema — validate the patched result against a schema.
  • JSON Formatter — pretty-print before pasting.
  • JSON Sort — canonicalise both target and result for stable hashes.

Versioning and Auditing Patches in Production

Once Merge Patch is in your production system, two related questions usually become important: how do you version the documents that get patched, and how do you audit the patches themselves? Both questions matter more than they appear, especially in regulated environments or when patches represent business-critical state changes.

On versioning, the canonical pattern is to attach a version identifier to each document — either an opaque ETag, an incrementing integer, or a timestamp — and require every patch request to specify which version it is patching. The server applies the patch only if the document is still at that version; otherwise it returns a conflict status, and the client must re-fetch and re-patch. This prevents the classic race where two clients fetch the same document, each computes a patch against it, and the second patch overwrites the first patch's changes silently. Either ETag-style optimistic concurrency or row-level versioning in your database supports this pattern, and either is far better than ignoring concurrency entirely.

On auditing, log every patch alongside the resulting document state. Just logging the patch is misleading: the same patch applied to different versions of a document produces different results, so a patch in isolation does not tell you what actually happened. Log the patch input, the document version it was applied against, and the resulting document version. Now your audit log is reproducible and unambiguous. This matters enormously when investigating a bug or responding to a regulatory inquiry — you can answer “what was the document state at time T, and what changed it” with confidence rather than reconstruction.

For especially sensitive operations, consider rejecting patches that introduce certain kinds of changes. A patch that flips a permissions field from “user” to “admin” might be valid Merge Patch syntax but should require additional authentication. Treat the patch format as a transport mechanism, not as a license to mutate arbitrary fields. Apply your authorization rules to the resulting state, not to the patch itself, and you maintain the same security posture you would have with full document replacement.

Production Patterns for JSON Merge Patch

RFC 7396 is small but has real subtleties in production:

Capture the Patch Result, Not Just the Patch

When auditing changes to a document, log both the patch and the resulting document. Patches alone are ambiguous — applying the same patch to different versions of a document gives different results, so the patch by itself isn't a reliable record of what actually happened.

Validate Before Patching

A patch can introduce a state your business logic considers invalid (negative balance, removed required field). Validate the POST-patch result against your JSON Schema before committing. If validation fails, reject the patch rather than rolling back later.

Idempotency for Retries

Merge Patch is idempotent in the sense that applying the same patch twice yields the same result — IF the document hasn't changed in between. In practice, network retries can hit a document that another writer mutated. Use ETags or version numbers to detect concurrent modification, and require the client to re-fetch + re-patch on conflict.

When to Use a Different Approach

Merge Patch isn't the right answer for every partial-update scenario:

  • Need to remove specific array elements?Merge Patch can't — it replaces arrays entirely. Use JSON Patch (RFC 6902) instead, which has explicit "op": "remove" with array indexes.
  • Need to modify deeply nested arrays? Same problem — Merge Patch replaces, JSON Patch mutates.
  • Want to compare two states, not apply a patch? Use JSON Diff for a structural comparison.

Common Mistakes to Avoid

  1. Sending null to keep a field unchanged. The semantic of nullin a Merge Patch is “delete this key” — NOT “no change”. To leave a key alone, OMIT it from the patch. This trips up almost everyone the first time.
  2. Trying to patch arrays element-by-element. You can't. Merge Patch treats arrays as opaque — to change array contents, you replace the whole array. If element-level mutation matters, use JSON Patch.
  3. Forgetting empty-object semantics. An empty object {}in a patch is NOT “remove the value at this path.” It's a recursive merge that does nothing (since there are no keys to merge). To remove, use null.
  4. Skipping content negotiation. The official content type for Merge Patch is application/merge-patch+json. Servers should reject patches sent as plain application/json— otherwise consumers can't tell which patch flavor your server accepts.
  5. Over-trusting client patches.Validate every patch's result against authorization rules. A patch from a non-admin user shouldn't be able to set role: "admin" just because Merge Patch allows it syntactically.

Real-World Use Cases

  • PATCH endpoints for REST APIs. Standard usage — client sends a partial document with only the fields to change, server merges it onto the stored record.
  • Configuration overrides. Ship a default config, allow environment-specific patches (a small Merge Patch per environment), apply at deploy time.
  • User preferences. Store user settings as a single document, accept tiny patches (one or two fields) from the client when settings change. Network footprint shrinks dramatically vs sending the whole settings object.
  • Bulk record updates.Apply the same patch to many records in a batch — efficient for “mark all as read” or “archive everything older than X.”

Wrapping Up

Merge Patch is small and elegant when its rules fit your use case — and frustrating when they don't. Use PDFFlare's JSON Merge Patch tool to dry-run patches in your browser, and reach for JSON Patch (RFC 6902) when null-as-value or array-element edits are on the requirements list.

Back to all posts