How to Combine JSON Files Fast

Working with multiple JSON exports from APIs can be tedious. Here is how to join them without writing a custom Python script every time.

The Challenge with JSON

Unlike flat CSV files, JSON data can be nested and complex. If you have arrays of objects from different API paginations, you need to concatenate those arrays into one master list. Writing a script to do this takes time and debugging.

The Quick Solution

Using a dedicated file merging tool simplifies this process. You can drag and drop your JSON files into the interface, and it will automatically detect the arrays and combine them.

• No need to worry about trailing commas.
• No need to write parsing logic.
• Instant preview of the merged data.

Array or Object: Decide Before You Merge

Every JSON merge starts with one question that determines everything else: what sits at the top level of your files? If each file contains an array of records, merging means concatenation. Take the elements of file two and append them after the elements of file one. This is the case when you are stitching together paginated API responses, exported database rows, or event logs, and it is by far the most common scenario.

If each file instead contains a single object at the top level, merging means combining keys. The result has the union of the keys from both files, and you need a rule for what happens when both define the same key. Configuration files, feature flag definitions and localisation bundles all work this way. Mixing the two shapes in a single operation has no sensible answer, which is why FileMerger asks you to pick rather than guessing and quietly producing something that looks right but is not.

When Both Files Define the Same Key

Key collisions are where object merges go wrong. The default in FileMerger is last file wins: load order determines precedence, and the file loaded later overrides values from earlier ones for any key they share. This makes the common configuration pattern work naturally. Load defaults.json first, then production.json, and the production values override the defaults while everything production does not mention falls through unchanged.

Nested objects are handled recursively rather than being replaced wholesale, which is the behaviour most people expect but many tools get wrong. If both files contain a "database" object, a shallow merge would discard the entire first version and keep only the second, silently dropping any key the second file happened to omit. A recursive merge descends into the object and combines it key by key, so a defaults file supplying a connection timeout and a production file supplying a hostname produce an object containing both.

Arrays Inside Objects Are a Special Case

A recursive merge has to make a decision when it reaches an array nested inside an object, and there is no universally correct answer. Consider two config files that each define a "allowedOrigins" array. Concatenating gives you every origin from both files, which is right if the arrays are additive lists of permissions. Replacing gives you only the later file’s list, which is right if the array is meant to be an exhaustive definition that the environment overrides completely.

FileMerger replaces nested arrays by default, matching the behaviour of most configuration systems, and offers concatenation as an explicit option. The important thing is to know which one you chose. A merged permissions list that silently accumulated entries from a stale file is a security problem, and a truncated list that dropped entries is an outage. Check the specific arrays that matter in the preview before you export.

Validate First, Merge Second

A merge inherits every problem in its inputs, so FileMerger parses and validates each file before the operation begins rather than failing halfway through and leaving you with partial output. The errors that show up most often in real exports are consistent:

• Trailing commas after the last element of an array or object. Valid in JavaScript source, invalid in JSON, and produced constantly by hand-edited files.
• Unquoted keys. JSON requires double quotes around every key; the bare-word form that JavaScript accepts is not valid JSON.
• Single quotes used for strings. JSON has no single-quoted string form, and this is the most common mistake when a file was pasted out of a JavaScript console.
• Unescaped control characters, usually literal newlines inside a string value, which appear when log output has been concatenated without escaping.

Newline-Delimited JSON Is Not an Array

Logging systems, data warehouses and streaming exports frequently emit NDJSON, where each line of the file is a complete, independent JSON document and the file as a whole is not valid JSON at all. Opening such a file with a normal parser fails immediately at the start of the second line, because the parser has finished reading one complete value and does not expect another to follow.

This format needs converting before it can be merged. Wrapping the whole file in square brackets and joining the lines with commas turns it into a proper array, after which it merges like any other array file. FileMerger detects the NDJSON pattern during validation and tells you what it found rather than reporting a generic syntax error at line two, which is otherwise a confusing message to debug.

Common Problems and What They Mean

The merged file is smaller than the inputs combined

This almost always means an object merge where you expected an array concatenation. Records with the same key overwrote each other instead of accumulating. Check whether your files really contain arrays at the top level, or whether each one wraps its records in an object keyed by identifier, which is common in exports from document databases.

Numbers changed slightly after merging

JSON has one numeric type and it maps to a double-precision float. Integers beyond roughly nine quadrillion, and long decimal identifiers, lose precision on parse regardless of the tool used. If your records carry large numeric IDs, the fix is to store them as strings in the source export rather than to look for a merger that handles them, because the loss happens at parse time.

Accented characters look wrong in the output

JSON is specified as UTF-8, but files exported from older systems are sometimes written in Latin-1 and mislabelled. The result is mojibake in string values. Re-export the source as UTF-8 if you can. If you cannot, convert the encoding before merging rather than after, because once two encodings are combined into one file the damage cannot be reliably undone.