Merging JSON Arrays: Concat, Union, Replace & Merge-by-Key
Arrays are the hardest part of merging JSON. Learn the four main strategies — concatenate, union, replace, and merge-by-key — and when to use each.
Merging objects is mostly intuitive: combine the keys. Merging arrays is where things get interesting, because there is no single “correct” way to combine two lists. This article walks through the four strategies you will actually use and shows how to pick the right one.
Why arrays are ambiguous
Given [1, 2, 3] and [3, 4, 5], what is the merge?
[1, 2, 3, 3, 4, 5]? (join them)[1, 2, 3, 4, 5]? (unique values)[3, 4, 5]? (the second one wins)
All three are reasonable depending on intent. That ambiguity is why array handling has to be an explicit choice, not a hidden default. Here are the four strategies worth knowing.
1. Concatenate
Concatenation joins the arrays end to end, keeping every item including duplicates.
[1, 2, 3] + [3, 4, 5] = [1, 2, 3, 3, 4, 5]Use it when each array is a stream of events, log entries, or records where duplicates are meaningful — for example, combining paginated API responses where the same value can legitimately appear twice.
2. Union (unique)
Union concatenates and then removes duplicate items, keeping the first occurrence.
[1, 2, 3] ∪ [3, 4, 5] = [1, 2, 3, 4, 5]This is the right call for sets: tags, permission lists, enabled feature names — anything where each value should appear once. Note that de-duplication is straightforward for primitives (numbers, strings) but requires a definition of “equal” for objects.
3. Replace
Replace discards one array entirely and keeps the other — usually the last input wins.
[1, 2, 3] then [3, 4, 5] = [3, 4, 5]Use replace when a later configuration is meant to override an earlier one completely. If your defaults say "plugins": ["a", "b"] and the override says "plugins": ["c"], replace gives you exactly ["c"] — the override fully controls the list.
4. Merge by key
The most powerful strategy treats an array as a collection of objects identified by a key (commonly id). Items with the same key are deep-merged; items with new keys are appended.
Given:
[{ "id": 1, "name": "Ada" }, { "id": 2, "name": "Alan" }]merged with:
[{ "id": 1, "role": "admin" }, { "id": 3, "name": "Grace" }]produces:
[
{ "id": 1, "name": "Ada", "role": "admin" },
{ "id": 2, "name": "Alan" },
{ "id": 3, "name": "Grace" }
]This is exactly what you want when arrays represent records — users, products, settings — and you are applying partial updates keyed by identity.
Choosing the right strategy
| Strategy | Keeps duplicates? | Best for |
|---|---|---|
| Concatenate | Yes | Logs, events, paginated streams |
| Union | No | Tags, sets, permission lists |
| Replace | N/A | Full overrides |
| Merge by key | Merges matches | Record collections, partial updates |
A common mistake
Most quick merge approaches — the spread operator, Object.assign, naive jq merges — replace arrays by default. Developers expecting concatenation or merge-by-key are often surprised when their second file’s array silently wins. Always confirm which strategy your tool uses.
Do it without code
Our JSON merge tool lets you pick any of these four strategies from a dropdown, including the key field for merge-by-key, and shows the result instantly. Combined with the choice of deep or shallow merge for objects, you get precise control over exactly how your data combines — no scripting required.
Takeaway
There is no universal way to merge arrays — only the right strategy for your data. Decide whether your arrays are streams, sets, overrides, or keyed records, and choose concatenate, union, replace, or merge-by-key accordingly.
Ready to merge your JSON?
Combine files or snippets in your browser — free and private.
Open the merge toolKeep reading