On-device AI — professional-grade, fully private.

Documents

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 filesWhat you wantSettings
Objects: a base config plus overridesOverrides change only the keys they nameDeep merge, Arrays: Replace
Arrays: several lists of records or log entriesOne long list with everythingArrays: Concatenate
Arrays of tags or values that repeatOne list, each value onceArrays: Union
Two exports of the same records with different fieldsOne record per id with all its fieldsArrays: Merge by key, Key field: id
Objects where nested sections should be swapped wholeA later section replaces the earlier one completelyShallow 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

1

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.

2

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.

3

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.

4

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.

5

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.

6

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 files

Deep 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:

  1. 1A key that exists in only one document is copied as it is. Nothing is lost and nothing is reported.
  2. 2Two objects at the same path are merged key by key (in Shallow mode, only at the top level).
  3. 3Two arrays at the same path follow the Arrays setting.
  4. 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.
  5. 5A later document that writes the identical value is not a conflict, so the report shows only real changes.
  6. 6An explicit null in 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 seeWhyFix
A row shows a line and column with a caretThat document is not valid JSONFix 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 offTurn it back on; config files such as tsconfig.json often carry comments
Inputs tab reports duplicate keysA file contains the same key twice, and only the last one survives parsingCheck which one you meant before trusting the merge
"Numbers lose precision"Integers above 9007199254740991, such as some 64-bit database ids, change when readStore such ids as strings in the source files
NDJSON is not availableThe merged result is an object, and NDJSON needs an arrayUse JSON, or merge array files
"Settings changed" badgeYou changed an option or the order after mergingPress Re-apply
"Preview shortened"The result is too long to show in fullNothing 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.

Keep reading

More in Documents →