Xerobit

JSON Merge: Combine Two JSON Documents

Paste two JSON values to merge them into a single document. Objects are combined recursively so nested keys from both sides are preserved, and arrays are concatenated. The json merge runs entirely in your browser and nothing is uploaded to any server.

Merged JSON

{
  "a": 1,
  "b": 2
}

How to use the json merge

  1. Paste your first JSON value into the First JSON text area.
  2. Paste your second JSON value into the Second JSON text area.
  3. Choose how arrays should be handled: concatenate, replace or union.
  4. The merged result updates automatically as you type.

How the json merge works

The tool performs a recursive deep merge when both inputs are JSON objects. For every key present in either object, the algorithm checks the types of the corresponding values.

  • If both values are plain objects, they are merged recursively.
  • If both values are arrays, the selected array mode applies (concatenation, replacement or union).
  • In all other cases, including mismatched types, the value from the second JSON overwrites the first.

For example, merging {"a": {"x": 1}} with {"a": {"y": 2}} produces {"a": {"x": 1, "y": 2}}. But merging {"a": 1} with {"a": [2]} replaces the number with the array because the types differ.

Array merge modes explained

When both inputs resolve to arrays at the same level, you can choose one of three strategies:

ModeInput AInput BResult
Concatenate[1, 2][3, 4][1, 2, 3, 4]
Replace[1, 2][3, 4][3, 4]
Union[1, 2, 3][2, 3, 4][1, 2, 3, 4]

Union mode removes duplicate primitives (strings, numbers, booleans, null) by strict equality. Objects and arrays inside the union are compared by reference, so two structurally identical objects will both appear in the output.

Handling unicode and special characters

JSON natively supports Unicode, so you can merge documents containing emoji, accented characters or non-Latin scripts without any data loss. The parser handles escape sequences like \u00e9 (which represents the character e with an acute accent) and converts them to their actual characters in the output.

Keys that contain spaces, dots or other special characters are preserved exactly as written. If both objects share a special-character key, the standard deep merge rules apply just as they would for simple alphabetical keys.

Common mistakes to avoid

A frequent error is pasting JavaScript object notation instead of valid JSON. JSON requires double quotes around all string keys and string values. Single quotes, trailing commas and unquoted keys will cause a parse error.

Another issue arises when mixing top-level types. If the first input is an object and the second is an array, the second value completely replaces the first because there is no meaningful way to combine an object and an array. Always ensure both inputs share the same top-level type if you expect a structural merge.

If you need to inspect the structure before combining, try the JSON formatter to validate each input separately. You can also use the JSON diff tool after merging to verify exactly what changed between the original and the result.

Practical use cases

Developers often need to combine configuration files where a base config is extended by environment-specific overrides. A json merge handles this cleanly: the base provides defaults and the override supplies only the keys that differ, leaving everything else intact.

Data pipelines sometimes receive partial records from different sources that need to be joined by a shared identifier. Merging the parsed JSON fragments reconstructs the full record without manual field mapping.

When working with APIs, you might need to combine a default request payload with user-supplied parameters. Deep merging ensures nested structures like headers or query options are correctly assembled rather than overwritten wholesale.

Worked examples

ExampleInputResult
Deep merge two objectsFirst JSON: {"a": 1, "b": {"x": 10}}; Second JSON: {"c": 3, "b": {"y": 20}}; Array handling: concat; Indent spaces: 2{ / "a": 1, / "b": { / "x": 10, / "y": 20 / }, / "c": 3 / }
Concatenate arraysFirst JSON: [1, 2]; Second JSON: [3, 4]; Array handling: concat; Indent spaces: 2[ / 1, / 2, / 3, / 4 / ]
Union of arraysFirst JSON: [1, 2, 3]; Second JSON: [2, 3, 4]; Array handling: union; Indent spaces: 2[ / 1, / 2, / 3, / 4 / ]

FAQ

Does this json merge tool upload my data?

No. All parsing and merging happens locally in your browser using JavaScript. Nothing is sent to any server.

What happens if a key exists in both JSON objects?

If both values are objects, they are merged recursively. Otherwise the value from the second JSON overwrites the first.

Can I merge a JSON object with a JSON array?

You can paste them, but because they are different types the second value will simply replace the first. A structural merge only occurs when both sides are objects or both are arrays.

Does the merge preserve key order?

Keys from the first object appear first, followed by any new keys introduced by the second object. This matches the standard behavior of JavaScript object property enumeration.

How does union mode handle duplicate objects inside arrays?

Union mode uses strict equality. Two separate objects with identical content are considered different, so both will appear in the result. Only primitive duplicates (numbers, strings, booleans, null) are deduplicated.

Can I format the output with a specific indentation?

Yes. Use the indent field to set the number of spaces from 0 to 8. Setting it to 0 produces compact single-line JSON.