JSON Merge — Deep-Merge Two JSON Documents

The whole algorithm fits in three rules. When a key holds an object on both sides, the two objects merge key by key, and the same rules apply one level down. When a key exists on only one side, it is kept as is. In every other case — scalar vs scalar, array vs array, or mismatched types — the Override value replaces the Base value. There is no third state and no heuristic: the same two documents produce the same result every time.

The rules compose in useful ways. Type conflicts resolve wholesale: if the Base holds an object at a key and the Override holds a string, the string wins, and the merge never tries to reconcile across types. An explicit null in the Override counts as a value — it overwrites the Base entry with null but keeps the key. That is a deliberate difference from JSON Merge Patch (RFC 7386), where null means "delete this key". This tool applies overlay semantics, not patch-with-deletion semantics.

Two output details are worth knowing. The result is pretty-printed with two-space indentation, ready to paste into a config file. And key order is stable: the Base keys come first in their original order, with keys that only exist in the Override appended after them — which is why debug lands at the end of the example above.

Consider ["auth"] merged with ["auth", "cache"]. Concatenation yields ["auth", "auth", "cache"] — a duplicated flag. Index-by-index merging pairs elements by position and produces nonsense the moment the lists differ in order or length. No strategy is right for every document, because the merge cannot know whether your array is a set of flags, an ordered pipeline, or a list of records with identities. Replacement is the one strategy that never needs that knowledge: the Override list is the complete new list.

Config-layering tools reached the same conclusion. Kubernetes replaces arrays outright in a plain merge patch (RFC 7386) and merges lists element-wise only in strategic merge patches, where the API schema explicitly declares a merge key for the field. In the webpack ecosystem, merge helpers that concatenate arrays by default ship replace strategies precisely because appended loader and plugin lists are a classic source of duplicates. Wherever a schema is unavailable — which is exactly the situation for a generic JSON tool — replacement is the convention.

The practical guidance follows directly. To keep Base entries, repeat them in the Override array; the example does this with "auth". And if you genuinely need element-level merging, restructure the list as an object keyed by id or name — {"auth": {...}, "cache": {...}} — merge, and convert back. Deep merge then operates per key, which is usually what "merge these arrays" meant in the first place.

Environment overlays are the canonical case: a base.json holding the full default configuration, plus a tiny staging.json or production.json that defines only what differs. Deep-merging them produces the effective config for that environment — and because overlays stay minimal, a review of staging.json shows you exactly what staging changes and nothing else. When an app behaves differently in one environment, merging the layers by hand here lets you read the effective config directly instead of simulating the layering in your head.

Feature flags and tenant settings follow the same shape. A default flag set deep-merges with a per-plan or per-tenant override: nested groups combine, individual toggles flip, and the flags the override never mentions keep their defaults. The third recurring case is API defaults — merging caller-supplied options over a defaults object before building a request, the deep version of what Object.assign and object spread do shallowly.

All three cases share a property that matters for a browser tool: the documents are often sensitive. Configs carry connection strings and API keys; tenant settings carry customer names. This merge runs entirely client-side, so pasting a production config here does not send it anywhere.

Merge and diff are inverse tools. A merge combines forward: given a Base and an Override, it produces the effective document. A diff looks backward: given two documents, it reports what changed between them without touching either. If you are holding two configs and wondering how they differ, you want the JSON Diff tool; if you already know the delta you want to apply, you want the merge.

They pair well in sequence. Diff the Base against the Override before merging to preview which keys the overlay will touch. Merge. Then diff the Base against the merged result to verify that only the intended keys moved — a two-minute audit that catches a mistyped key in an overlay before it ships. Both tools work on parsed structure rather than text, so indentation and whitespace differences never pollute the comparison. And when the merged document is the one you will deploy, open it in the editor to validate it and walk the final structure as a tree.