JSON Deep Merge
Deep-merge two JSON documents.
Overview
The JSON deep merge combines two JSON documents into one, recursively merging objects and replacing scalars. It's the JSON equivalent of _.merge from Lodash or **dict1, **dict2 semantics extended to nested keys — except both inputs and output stay as canonical JSON.
It's useful for layering config (defaults plus environment-specific overrides), composing Helm-style values files, or stitching together fixture data from two sources. Developers and DevOps engineers use a json merge tool to validate the result of an override pattern before committing it to source.
How it works
The merge walks both documents in lock-step. When both sides have an object at the same key, the merge recurses into them. When one side has a scalar (string, number, boolean, null) and the other has anything, the second document's value wins. Arrays are replaced by default rather than concatenated — that matches what most config systems (Kubernetes, Helm) actually do, and avoids surprising duplicate elements.
Toggle the array strategy if you need concatenation, or a unique-merge that deduplicates by value. Output indentation matches the formatting options of the JSON formatter, so the merged document is ready to commit.
Examples
Base: {"a": 1, "b": {"x": 10, "y": 20}}
Override: {"b": {"y": 99, "z": 30}, "c": 3}
Merge:
{
"a": 1,
"b": { "x": 10, "y": 99, "z": 30 },
"c": 3
}
Arrays replaced:
Base: {"tags": ["a", "b"]}
Override: {"tags": ["c"]}
Merge: {"tags": ["c"]}
Arrays concatenated (opt-in):
Merge: {"tags": ["a", "b", "c"]}
FAQ
Which side wins on a conflict?
The second document (the override) wins for scalars and arrays. Objects are merged key-by-key rather than replaced, so partial overrides work as expected.
Can I merge more than two documents?
Merge the first two, then merge the result with the third, and so on. The operation is left-associative, so the final document wins for every conflicting key.
Does it perform a JSON Patch?
No — that's a separate spec. For RFC 6902 patches (add/remove/replace operations), use the JSON patch tool. Deep merge is for whole-document overlay.