How to Merge JSON Files Online (and What Happens When Keys Conflict)
Merge JSON files into one: deep or shallow, four ways to combine arrays, and a report of every value a later file overwrote. Free for up to 5 files.
Updated November 8, 20269 min read
To merge JSON files, add them to the JSON merger in the order you want them applied, choose Deep merge or Shallow merge, pick what should happen to arrays, and press Merge JSON. The result downloads as one file. The order is the rule for conflicts: where two files set the same key, the later file wins, and the Conflicts tab lists every value that was overwritten, with the old value and the new one. The free plan takes up to 5 documents, 10 MB each and 30 MB in total, and it all runs on your device, not our servers. The rest of this guide explains which settings fit which job, because "merge" means three quite different things depending on what your files hold.
Merging JSON files: three different jobs
Before choosing settings, look at the outermost brackets of your files. A file that starts with { is an object (named keys); one that starts with [ is an array (a list). What you want from the merge depends on that, and on whether the files describe the same things or different ones.
| Your files | What you want | Settings |
|---|---|---|
| Objects: a base config plus overrides | Overrides change only the keys they name | Deep merge, Arrays: Replace |
| Arrays: several lists of records or log entries | One long list with everything | Arrays: Concatenate |
| Arrays of tags or values that repeat | One list, each value once | Arrays: Union |
| Two exports of the same records with different fields | One record per id with all its fields | Arrays: Merge by key, Key field: id |
| Objects where nested sections should be swapped whole | A later section replaces the earlier one completely | Shallow merge |
The tool accepts any JSON root, so you can merge objects with objects, arrays with arrays, or mix them. When the two values at the same place are of different types (an object meeting an array, a number meeting a string), they cannot be combined, so the later one replaces the earlier one and the replacement is recorded as a conflict.
How to combine JSON files into one, step by step
Add the documents
Drop up to five .json, .jsonc, .jsonl or .ndjson files onto the JSON merge tool, or press Paste JSON to type or paste a document in. You can mix files and pasted text.
Put them in order
The first document is the base and each later one is laid on top of it. Use the Move earlier and Move later arrows on each row so that the file whose values should win is last.
Choose how objects combine
Under Objects, Deep merge combines nested objects key by key; Shallow merge combines only the top-level keys and replaces nested objects whole. Deep is the default.
Choose how arrays combine
Under Arrays, pick Replace, Concatenate, Union or Merge by key. For Merge by key, type the Key field that identifies a record (it defaults to id). Set Null values to Ignore if a null in a later file must never erase a value.
Merge and check
Press Merge JSON. Read the Conflicts tab to see what was overwritten and the Inputs tab for duplicate keys or precision warnings found in each source.
Download or copy
Pick an Indent (Minified, 2 spaces, 4 spaces or Tab) and a Format (JSON, or NDJSON when the result is an array), then press Download JSON or Copy.
Deep or shallow merge, four array strategies, a null policy and a conflict report, all free. Free: up to 5 documents, 10 MB each and 30 MB in total. Pro: up to 100 documents, limited only by your device, plus ZIP delivery.
Merge JSON filesDeep merge vs shallow merge
Take a base file {"server": {"host": "localhost", "port": 8080}} and an override {"server": {"port": 9090}}. With Deep merge the result is {"server": {"host": "localhost", "port": 9090}}: the tool goes inside server and changes only the key the override mentions. With Shallow merge the result is {"server": {"port": 9090}}: the whole server object from the later file replaces the earlier one, and host is gone.
Deep is what you want for layered configuration (base, then production, then local overrides), for translation files split across teams, and for test fixtures where each case changes a few fields. Shallow is right when each top-level section is a self-contained unit and a later file is meant to supply a complete replacement, for example a whole database block for another environment.
Combining JSON arrays: replace, concatenate, union or by key
There is no single correct way to merge two lists, so the tool asks. The setting applies wherever two arrays meet: at the top of the file, and at any nested path in Deep mode (or at a top-level key in Shallow mode).
- Replace (the default): the later array wins outright.
[1, 2]and[3]give[3]. - Concatenate: every item from both arrays, in order, duplicates included.
[1, 2]and[2, 3]give[1, 2, 2, 3]. Use it for logs, events and record exports that do not overlap. - Union: both arrays joined, then repeated items removed.
[1, 2]and[2, 3]give[1, 2, 3]. Objects are compared by content, so{"a":1,"b":2}and{"b":2,"a":1}count as the same item. - Merge by key: records that share a Key field value are combined field by field; records with a new key are appended at the end; items that are not objects or lack the key are appended untouched.
Merge by key matches on type as well as value. A record with "id": 1 and one with "id": "1" are different records and are not joined. If your two exports disagree on whether ids are numbers or strings, fix one of them first, or the result will contain both versions side by side.
What happens on a key conflict, exactly
A conflict is any place where a later document replaced a value instead of merging into it. These are the rules the merger follows, in full:
- 1A key that exists in only one document is copied as it is. Nothing is lost and nothing is reported.
- 2Two objects at the same path are merged key by key (in Shallow mode, only at the top level).
- 3Two arrays at the same path follow the Arrays setting.
- 4Anything else, such as two different numbers, a string meeting an object, or an object meeting an object under Shallow merge, is replaced by the later value and recorded as a conflict.
- 5A later document that writes the identical value is not a conflict, so the report shows only real changes.
- 6An explicit
nullin a later file overwrites by default, because null is a real JSON value. With Null values set to Ignore, it is skipped and the report counts how many nulls were ignored.
The Conflicts tab shows each one as a row: the Path (such as $.server.port), what it Was, what it is Now, and the document it came From. The first 500 conflicts are listed in full and the count keeps going beyond that. If the tab says nothing was overwritten, every value from every document is in the result.
Key order follows the base document by default, with keys that appear only in later files added at the end, which keeps a version-control diff small. Choose Key order: A to Z when you want the same output however the inputs happened to be written.
Things that go wrong, and what to do
| What you see | Why | Fix |
|---|---|---|
| A row shows a line and column with a caret | That document is not valid JSON | Fix it with the JSON Validator or JSON Formatter, then merge again |
| "There is a comment, and strict input is turned on" | Accept comments and trailing commas is off | Turn it back on; config files such as tsconfig.json often carry comments |
| Inputs tab reports duplicate keys | A file contains the same key twice, and only the last one survives parsing | Check which one you meant before trusting the merge |
| "Numbers lose precision" | Integers above 9007199254740991, such as some 64-bit database ids, change when read | Store such ids as strings in the source files |
| NDJSON is not available | The merged result is an object, and NDJSON needs an array | Use JSON, or merge array files |
| "Settings changed" badge | You changed an option or the order after merging | Press Re-apply |
| "Preview shortened" | The result is too long to show in full | Nothing is missing: the download contains the whole result |
The free limit that usually stops a merge is the 30 MB total rather than the 10 MB per file, because the tool holds every input and the merged result in memory at once. Five files of 8 MB each, 40 MB together, are over the total even though each file is under the per-file cap. Removing whitespace with the JSON Minifier first often brings a set under the limit without changing any data.
After the merge: check it and tidy it
To see the merge from the other side, compare the merged file with your base file in JSON Diff: every addition and change will be listed by path. Reading that report is covered in how to compare two JSON files. If several tools regenerate the merged file, sort its keys so the order stays stable between runs. And if your data is really a spreadsheet export, merging CSV files keeps it in rows and columns instead.
Frequently asked questions
How do I merge two JSON files into one?
Add both files to the JSON merger with the file whose values should win in second place, keep Deep merge selected, and press Merge JSON. Then download the result. Free covers up to 5 documents, 10 MB each and 30 MB in total.
How do I combine JSON files that are arrays into one array?
Set Arrays to Concatenate before merging. On the default, Replace, the later array wins and you get only the last file's items. Choose Union instead to drop repeated items, or Merge by key to join records that share an id.
Which value wins when two JSON files have the same key?
The later document in the list. If both values are objects they are combined (in Deep mode); otherwise the later value replaces the earlier one, and the Conflicts tab records the path, the old value, the new value and which document won.
What is the difference between deep merge and shallow merge in JSON?
Deep merge goes inside nested objects and changes only the keys a later file names. Shallow merge works on top-level keys only, so a nested object in a later file replaces the earlier nested object completely, including keys it did not mention.
Can I stop null values from erasing data when merging JSON?
Yes. Set Null values to Ignore. A null in a later file is then skipped wherever a value already exists, and the merge report tells you how many nulls were ignored. On Overwrite, the default, a null replaces the earlier value.
Can I merge JSON files with comments or JSON Lines?
Yes. With Accept comments and trailing commas switched on, which is the default, files with // or /* */ comments and trailing commas are read normally. NDJSON and JSON Lines files are read as an array, and an array result can be written back as NDJSON.