JSON Merge

What Is JSON Merge?

JSON Merge is the operation of combining two or more JSON objects into a single output object. The resulting object contains the keys and values from all input objects, with a defined rule governing what happens when two inputs share the same key. It is one of the most common transformations in JavaScript development and API integration work, and understanding its two distinct modes, shallow merge and deep merge, is essential for avoiding subtle data-loss bugs.

JSON itself is defined by RFC 8259, the IETF standard that specifies the six permitted value types: string, number, boolean, null, object, and array. A merge operation works at the level of JSON objects, combining their top-level keys and, in the case of a deep merge, recursively combining nested objects rather than replacing them outright. The distinction matters enormously in practice: choosing the wrong merge strategy is one of the most common sources of silent data loss in configuration management and API integration code.

In a shallow merge, only the top-level keys are combined. If both input objects have a key with the same name and that key holds a nested object, the right-hand object's nested value completely replaces the left-hand one. None of the left-hand nested object's properties survive. In a deep merge, nested objects are merged recursively at every level, so both inputs contribute their properties. The choice between shallow and deep merge depends entirely on whether you want nested objects replaced or combined.

This tool performs both types of merge in your browser. Your data is never sent to a server. You can safely paste configuration objects, API response fragments, or any JSON data you need to combine, without concern for data privacy.

How to Use the JSON Merge Tool

1. Paste your first JSON object into the left input panel. This is the base object whose properties will appear in the output. Ensure it is valid JSON, meaning all keys and string values are double-quoted, and the structure starts and ends with curly braces for an object or square brackets for an array.
2. Paste your second JSON object into the right input panel. This is the object whose properties will be merged into the base. Where both objects share a key, the value from this second object will take precedence in the output.
3. Select your merge strategy. Choose shallow merge if you want top-level keys combined and nested objects replaced wholesale by the right-hand side. Choose deep merge if you want nested objects recursively combined so that both sides contribute their properties at every depth level.
4. Click "Merge". The tool combines both inputs according to the selected strategy and displays the resulting JSON object in the output panel.
5. Review the output carefully. Check that keys from both inputs appear as expected and that nested objects have been handled according to your intention. Pay particular attention to any keys that existed in both inputs.
6. Copy or download the result. Copy the merged JSON to your clipboard for immediate use, or download it as a .json file if you intend to save it as a configuration file, fixture, or input to another process.

Why Use This Tool

Merging JSON objects is a task that appears constantly in modern development work: combining default configuration with environment-specific overrides, merging API response fragments, building composite data objects for testing, and reconciling settings from multiple sources. The native JavaScript approaches all have trade-offs that are not immediately obvious, which is why a browser-based tool that makes the merge strategy explicit and shows the result immediately is genuinely useful.

JavaScript's Object.assign() and the spread operator ({ ...obj1, ...obj2 }) both perform shallow merges. They are fast and require no dependencies, but they silently discard nested properties when keys collide. As documented in the MDN Web Docs reference for Object.assign(), the method copies own enumerable properties from one or more source objects to a target, but it does not recurse into nested objects. Many developers discover this limitation only after a bug in production caused by a nested configuration key being wiped out silently.

Configuration management

Applications that load configuration from multiple sources, such as a base config file, an environment-specific override file, and environment variable injections, need a reliable deep merge to combine them. Tools such as Webpack and Vite use deep merging internally to allow partial configuration overrides without requiring users to replicate the entire base configuration in their override file.

API response reconciliation

When two separate API endpoints each return a partial representation of the same entity, a merge operation produces the complete record. For example, a user profile endpoint might return basic account details while a separate preferences endpoint returns display and notification settings. Merging the two responses gives the full user object needed to render a complete profile page.

Feature flag and settings composition

Applications that support feature flags, tenant-specific settings, or per-user overrides typically store a base settings object and apply progressively more specific overrides on top. A deep merge correctly composes these layers while preserving any nested settings that the more specific override did not explicitly change.

Real-World Use Cases

Frontend developer merging default props with user-defined overrides

A React developer at a design-system agency is building a configurable chart component. The component has a large default configuration object covering colours, font sizes, grid lines, axis labels, and animation timing. When a consumer of the component passes a partial configuration override, the component needs to merge the override with the defaults so that only the specified properties change. The developer uses a deep merge to combine the two objects, ensuring that specifying a custom colour does not accidentally wipe out the default font size settings nested inside the same configuration branch. Testing the merge behaviour with this tool before implementing the logic in code prevents the bug from reaching the codebase at all.

DevOps engineer composing environment-specific configuration

A DevOps engineer at a London-based SaaS company maintains configuration for three environments: development, staging, and production. Each environment shares most settings but overrides a small number of values such as database connection strings, log levels, and feature flags. She stores a base configuration as a JSON file and a separate override file for each environment. Using a deep merge, she combines the base with the appropriate override at deployment time to produce the final configuration. This approach means the base file is the single source of truth for 90% of settings, and the override files are small and easy to review in pull requests.

Backend developer combining partial API responses

A backend developer at an e-commerce company is building a product detail page that aggregates data from three microservices: one for core product data, one for pricing and inventory, and one for reviews and ratings. Each service returns a JSON object keyed to the product ID. The developer merges all three objects into a single product record before serialising it as the page API response. Using a shallow merge is sufficient because none of the three services share nested object keys, and the merge produces the complete product object in a single step without any manual key-copying.

Data engineer reconciling records from two data sources

A data engineer at a media company is reconciling article metadata from two systems: a legacy CMS and a new headless CMS. Both systems export JSON records for each article, but neither contains the complete set of fields. The legacy system has publication dates, author IDs, and category tags. The new system has SEO metadata, canonical URLs, and structured data markup. The data engineer uses the JSON Merge tool to combine sample records from both systems during the design phase, verifying the merged structure before writing the reconciliation pipeline in Python. The visual confirmation that both sets of fields appear correctly in the output saves an iteration of pipeline development.

Common Mistakes and Troubleshooting

Using a shallow merge when nested objects need to be combined

This is the single most common merge mistake. If both input objects contain a key whose value is itself an object, a shallow merge will discard all properties from the left-hand nested object and replace it entirely with the right-hand nested object. If you are merging configuration objects, user settings, or any data with nested structure, always use a deep merge unless you explicitly want the right-hand nested object to fully replace the left-hand one. Inspect the output carefully to confirm nested properties from both inputs are present.

Expecting arrays to be merged element-by-element

Neither shallow nor deep merge combines arrays intelligently by default. When both inputs share a key whose value is an array, the right-hand array replaces the left-hand array entirely, regardless of whether you use shallow or deep merge. If you need to concatenate or union arrays from two objects, you must handle the array keys separately before or after the merge, using JavaScript's Array.prototype.concat() or a spread-based approach such as [...arr1, ...arr2].

Merging JSON arrays instead of JSON objects

The JSON Merge operation is defined for objects (key-value maps). If you paste two JSON arrays (values starting with [) and expect them to be merged as objects, the result will not be what you expect. To combine two arrays, use a concatenation operation, not a merge. If you intended to merge objects, check that your input starts with { and ends with }.

Key collision order misunderstanding

When both input objects share a top-level key with a scalar value (string, number, boolean, or null), the second object's value always wins. If you paste object A on the left and object B on the right, and both have a "status" key, the output will contain object B's value for "status". If you expected the opposite, swap the order of your inputs and merge again.

Invalid JSON in one of the inputs causing a silent failure

If either input contains invalid JSON, for example a trailing comma, single quotes around keys, or an unescaped special character, the tool cannot parse it and will not produce output. Check both inputs independently by pasting each one into a JSON validator before attempting the merge. The most common causes of invalid JSON are trailing commas after the last key in an object, JavaScript-style comments (which are not permitted in JSON), and keys that are not enclosed in double quotes.

Assuming the merged output preserves key order

The JSON specification does not define a required key order for objects, and the ECMAScript specification notes that while modern JavaScript engines do preserve insertion order for string keys in practice, you should not rely on a specific key order in merged output for logic or display purposes. If a downstream system requires keys in a specific order, apply an explicit sort after the merge rather than assuming a particular order will be preserved.