JSON Merge

What this tool is used for

• Layering an environment override file on top of a base configuration to see the effective result.
• Combining a default settings object with a user's saved preferences before debugging which wins.
• Building a single fixture from two partial API responses.
• Checking whether a deep merge or a shallow one is what your library actually performs.
• Producing a merged payload to send in one request instead of two.

Frequently Asked Questions

What is the difference between a shallow and a deep merge?

A shallow merge replaces whole top-level values, so a nested object in the second input overwrites the first entirely. A deep merge recurses and combines them key by key. Most surprises come from expecting deep and getting shallow.

How are arrays handled?

This is the genuinely ambiguous case with no universal answer: replace, concatenate, or merge by index. JSON Merge Patch (RFC 7396) specifies REPLACE, which surprises people expecting their list to be appended to.

How do I delete a key when merging?

Under RFC 7396, setting a key to null removes it. That is why a plain deep merge cannot express deletion, and why a config value legitimately set to null cannot be represented in a merge patch at all.

What is the difference from JSON Patch?

JSON Merge Patch (RFC 7396) looks like the document and is easy to read but cannot delete-versus-null or touch array elements. JSON Patch (RFC 6902) is an explicit list of add/remove/replace/move operations — more verbose, fully expressive.

Which input wins on a conflict?

The later one, by convention — the same rule as Object.assign and spread. Order therefore matters, and merging defaults over user settings rather than under them is a frequent bug.

What happens when the two sides have different types for a key?

The incoming value replaces the existing one outright — an object does not merge into a string. This is where silent data loss hides, because the result is valid JSON and nothing reports that a whole subtree was discarded.

Is merge order associative?

For a deep merge of plain objects, yes. It stops being so once arrays are involved, because replacement is not associative: merging A into B into C can differ from A into the result of B into C depending on which array wins.

Common errors and gotchas

• Expecting arrays to combine. Most merges replace an array wholesale rather than concatenating or unioning it.
• Choosing a shallow merge and losing every nested key that the right side did not mention.
• Assuming `null` on the right removes a key. In most implementations it sets the value to null instead.
• Forgetting that key order in the output is not meaningful, then diffing the result and seeing noise.
• Merging objects whose numeric keys look like array indices, which produces something neither side intended.