`RFC 7396` merge patch -- the simple alternative to JSON Patch
JSON Merge Patch (RFC 7396) defines a straightforward algorithm: take a base document and a patch document, merge them recursively. Keys present in the patch overwrite the corresponding keys in the base. Keys set to null in the patch are deleted from the result. Keys absent from the patch are left untouched. Unlike JSON Patch (RFC 6902), there is no operation array, no "op": "add" / "remove" / "replace" -- the patch document is just the desired diff expressed as plain JSON. This tool applies that algorithm and shows you exactly what changed.
Applying a merge patch
- 1Paste your base JSON document on the left.
- 2Paste the merge patch on the right. Set any key to
nullto remove it; set it to a new value to add or update. - 3Click Merge. The result appears in the output panel with color-coded badges showing how many keys were added, removed, or modified.
Merge semantics in detail
- Recursive deep merge — When both the base and patch have an object at the same key, the merge recurses into that object rather than replacing it wholesale. This preserves sibling keys in nested structures.
- `null` means delete — Per
RFC 7396section 2, anullvalue in the patch explicitly removes that key from the result. This is the only way to express deletion in a merge patch. - Array replacement, not merge — Arrays in the patch replace the entire array in the base -- they are not merged element-by-element. This is a deliberate
RFC 7396design choice. - Non-object patch passthrough — If the patch is not an object (e.g., a string or number), it replaces the base entirely. The tool handles this edge case per spec.
- Change summary badges — After merging, the output shows added (green), removed (red), and modified (yellow) counts for top-level keys, giving you a quick diff summary.
Practical applications
- PATCH endpoint testing — Many REST APIs accept
application/merge-patch+jsonfor partial updates. Preview the merge result before sending the request. - Config overlay systems — Tools like Kustomize and Helm use merge-patch semantics for overlaying configuration. Visualize the merged output to catch unintended overwrites.
- Feature flag management — Merge a feature-flag patch into a base config to see the effective state without deploying.
- Database migration previews — When migrating document stores (MongoDB, CouchDB), preview how a merge patch transforms existing documents.
Merge patch walkthrough
// Base document:
{
"name": "Alice",
"age": 30,
"city": "New York",
"nickname": "Ali"
}
// Patch:
{
"age": 31, // modified
"city": "Boston", // modified
"nickname": null, // deleted
"country": "USA" // added
}
// Result:
{
"name": "Alice",
"age": 31,
"city": "Boston",
"country": "USA"
}`RFC 7396` nuances
Why does null delete instead of setting the value to null?
RFC 7396 explicitly defines null in a patch as a deletion signal. This means you cannot use merge patch to set a value to literal null -- that is a known limitation of the format, acknowledged in the RFC itself.
How is this different from JSON Patch (`RFC 6902`)?
JSON Patch uses an array of operations (add, remove, replace, move, copy, test) with explicit paths. Merge Patch uses the document structure itself as the diff. Merge Patch is simpler but less expressive -- it cannot reorder arrays, move keys, or set values to null.
What happens when both base and patch have an array at the same key?
The patch array replaces the base array entirely. There is no element-level merging. If you need array-level control, use JSON Patch (RFC 6902) instead.
Can I merge more than two documents?
Apply patches sequentially: merge the base with the first patch, then merge the result with the second patch. The algorithm is associative, so the order of patches determines the final state.