Merge JSON files with rules you control
Use this tool to combine two or more JSON documents into one merged JSON result. Load files by dropping or browsing, or paste each document as JSON. The tool supports object and array roots, shallow or deep merging, configurable precedence, a null policy, and array handling. It also creates a JSON merge report.
Choose the merge settings
Set the controls to update the merge automatically:
- Select Object root (merge as key/value maps) or Array root (merge as top-level arrays). Every document must use the selected root type.
- Choose Deep (recursive merge at every level) to merge nested objects by key, or Shallow (top-level keys only) to resolve a nested object as one value.
- Set Precedence for scalar & type conflicts to First document wins or Last document wins.
- Choose Null is a value or Null means absent. The latter ignores null when another source supplies a real value, and uses null only when every source has null.
- Choose Replace, Concatenate, Union, or Merge by key under Global array handling. The first three use precedence, source order, or full-value deduplication as shown by their labels.
- For Merge by key, enter the Global array merge key field. You can also add a Per-path array override and enter its Path, Handling, and Key field (for "merge by key").
Path overrides use exact dot notation, such as items or a.b.list. The tool does not check whether the path exists.
Review conflicts and validation results
Malformed JSON is rejected when it is added. The parser error is shown and, when a character position is available, the tool adds line and column information. A root-type mismatch blocks the merge instead of wrapping the document.
After the documents and settings are valid, inspect the automatically updated Output tree and conflict table. The table shows paths, conflict kinds, summarized candidate values, and the selected resolution. Serialized values longer than 200 characters are shortened in this display and report. With Null means absent, a null-versus-value case can resolve without a conflict entry because the null is removed before comparison.
How to merge JSON
- Drop JSON files on Drop JSON files here or click browse files. Alternatively, paste a document into JSON document, optionally enter Document name (optional), and click Add document.
- Add at least two valid JSON documents. Each top-level value must be an object or an array.
- Choose the root type and merge settings. If you use Merge by key, enter the required key field.
- The merge runs automatically once at least two valid documents are loaded.
- Review the Output tree and the conflict table.
- Click Export merged JSON or Export merge report (JSON).
Important limitations
- If no key field is entered for Merge by key, the tool falls back to Replace using precedence and records an
array-key-merge-missing-keyconflict. - Merge by key matches only non-array objects that contain the configured field. Other items stay in source order.
- An incorrect or unused dot-notation override may have no effect because paths are matched exactly and are not validated.
- Root-type mismatches block the merge, and fewer than two documents cannot be merged.
Processing and downloads
The inspected implementation reads selected files with FileReader. It creates the merged JSON and report downloads with Blob and object URLs. No upload call is present in this tool implementation. This tool combines JSON; it does not diff documents, flatten them, or join tabular records.
Frequently Asked Questions
What's the difference between shallow and deep merge here?
Deep (recursive) merge combines nested objects key by key at every level. Shallow merge only combines top-level keys - if a key's value is itself an object at a deeper level, the whole nested object is treated as a single conflicting value and resolved by precedence rather than merged key by key.
How are conflicting scalar values resolved?
You choose a global precedence: first document wins or last document wins. The selected value is shown in the conflict report with summarized candidate values; serialized values longer than 200 characters are truncated.
How does array handling work?
You set a global default (replace, concatenate, union by full value, or merge arrays of objects by a chosen key field) and can override it for specific paths. Replace picks one array by precedence; concatenate appends all arrays in source order; union deduplicates by deep value equality; key-merge matches array items across sources by a key field and merges matched items using the same shallow/deep rules as objects.
What does the null policy control?
It decides whether an explicit null in one document can override a real value in another. "Null is a value" treats null like any other value in conflict resolution. "Null means absent" ignores null values when other sources provide a real value for the same path, only using null if every source has null there.
What happens if my JSON is malformed or the root type doesn't match?
Malformed JSON is rejected when it is added. The parser error may include line and column information when a character position is available. Root type (object vs. array) is explicit, and a mismatch blocks the merge rather than silently wrapping the document.
Does this tool compare, diff, flatten, or upload my JSON?
No. It combines documents according to the rules you set; it does not report structural differences, flatten nested structures into tabular rows, or join tabular records by keys. The implementation reads files locally with FileReader, creates downloads with Blob and object URLs, and contains no upload call.