How to Compare Two JSON Files (and Why a Plain Text Diff Misleads You)
Compare two JSON files and see exactly which keys were added, removed or changed. Why text diffs are noisy, how arrays are matched, and what to ignore.
Updated November 7, 20268 min read
To compare two JSON files, open the JSON diff tool, drop one file on each side (or paste the text), and read the list of differences. Each one is marked added, removed, changed or type changed, with the exact path to the value. It compares the data, not the text, so reordered keys and different indentation do not show up as changes. That is the whole reason to use it instead of a plain text diff.
Why a text diff of JSON is so noisy
A text comparison works line by line. JSON does not care about lines. These two documents hold exactly the same data, yet a text diff marks every line as different: one is written on a single line, the other is indented with four spaces, and the keys come in a different order.
| What differs | Text diff says | The data says |
|---|---|---|
| Indentation (2 spaces vs 4, or a tab) | Every line changed | Nothing changed |
| Whole file minified onto one line | One line replaced by another | Nothing changed |
| Keys in a different order | Lines moved or rewritten | Nothing changed: objects have no order |
| 1 written as 1.0 | Line changed | Same number |
| A price going from 9.99 to 10.99 | One line changed | One value changed |
The last row is the one you care about, and in a text diff it is buried under the first four. Many APIs return keys in a different order on each call, and many tools rewrite the indentation when they save a file, so the noise is the normal case, not the exception.
Comparing two JSON files, step by step
Add the left document
Open the JSON diff tool. Paste the original into the box marked Left (original), or drop a .json file on the drop area. The tool also opens .jsonc, .geojson, .map and .txt files.
Add the right document
Paste or drop the changed version into Right (changed). If you drop both files at once, they are paired by name, so billing.before.json and billing.after.json land on the correct sides. Use Swap sides if they ended up the wrong way round.
Read the differences
The comparison runs as you type. Choose Side by side, Inline or By path. The summary shows how many were added, removed and changed, and the Next change and Previous buttons jump between them. Use the filter to show only added, removed, changed or type changes.
Tune what counts as a difference
Open the comparison settings to ignore array order, case or whitespace, set a number tolerance, or skip keys that always change. The next sections explain each.
Export if you need a record
Copy summary puts a plain list of changes on your clipboard. Download JSON Patch gives a standard file that turns the left document into the right one. Download Markdown gives a report you can paste into a ticket or a pull request.
Compare two documents and see every added, removed and changed value by path. Free: one pair at a time, up to 10 MB per side, with every option and export included. Runs on your device, not our servers.
Compare two JSON filesWhat the report tells you: added, removed, changed
The tool walks both documents together and reports each difference with its location. Objects are compared key by key, at any depth. A key that exists only on the right is added. A key that exists only on the left is removed. A key present on both sides with a different value is changed. A value whose kind has changed, such as the text "3" becoming the number 3, is reported separately as type changed, because it is the kind of change most likely to break whatever reads the file next.
Locations are written as paths. Under By path you see where each change sits, for example the name of the second item in a users list. The exported patch uses the standard JSON Pointer form (/users/1/name), which is unambiguous even when a key contains a dot or a slash.
- Numbers are compared by value, so 1, 1.0 and 1e0 are the same number and are not reported.
- Reordering the keys of an object is never a change.
- The top level can be anything JSON allows: an object, an array, or even a single string or number.
- If a document declares the same key twice, the tool warns you, because parsers silently keep only the last value and a difference in the earlier one is invisible.
How arrays are compared
Arrays are where JSON comparisons go wrong. If two lists are compared strictly position by position, adding one item at the front makes every later item look different. The tool avoids that by lining the items up first, and it shows which strategy it used next to the summary.
| Strategy | When it is used | Good for |
|---|---|---|
| By id | You name a field under Match array items by field and every item has a unique value in it | Records from an API that came back in a different order |
| By longest common subsequence | The default | Lists where items were inserted or removed |
| As a set | Ignore array order is on | Tags, permissions, anything where order means nothing |
| By position | The two lists have almost nothing in common | Lists that really were replaced |
Matching by id is the one to reach for with lists of records. Type the field name (id is the usual one) and a reordered list reads as reordered, with only the record that really changed reported. The tool uses the field only if every item has it and no value repeats. If it did not, it would produce a tidy but wrong pairing, so it falls back to the default instead of guessing.
Ignore the noise: keys, paths, case and numbers
A strict comparison is the default: every value, type and array position must match. Each setting relaxes exactly one thing, and the exported report records which ones were on.
- Keys to ignore: list names such as updatedAt or requestId, separated by commas. They are skipped wherever they appear, at any depth. This is what turns two API snapshots into a readable diff.
- Paths to ignore: skip one location, with * for one step and ** for any number. /users/*/lastSeen skips that field for every user.
- Ignore case and Ignore whitespace: for labels that changed style, or descriptions that were re-wrapped.
- Number tolerance: how close two numbers must be to count as equal. A tolerance of 0.0001 hides float rounding noise while a real price change still shows.
- Allow comments and trailing commas: for config files written as JSONC.
Typical jobs: API changes and config drift
For an API that changed, save the response before and after, add the changing fields (timestamps, request ids, etags) to the ignored keys, and what remains is the real change in shape. For config drift between two environments, such as staging and production, load both files and look at By path: it lists exactly which settings differ, and nothing else. For a migration or export, compare the old and new files and download the Markdown report as the record of what moved.
If you want to keep comparing with an ordinary text diff, for example inside a code review tool, first make both files look the same: run each through the JSON formatter with the same indent, and put the keys in one order with sort JSON keys. Sorting keys moves only the keys, and the values are not touched. That removes most of the text noise, but it cannot do what the diff tool does with arrays, tolerances or ignored fields.
Limits and what goes wrong
- Size: Free compares one pair at a time, up to 10 MB per side. Pro raises the size to what your device can handle and compares up to 50 pairs at once, paired by file name, with all reports and patches in one ZIP. A file over the free limit is refused with its real size, and a link to the minifier, because pretty-printed JSON is often mostly indentation.
- Other formats: YAML, XML, CSV and Excel files are refused at the door with a link to the right converter, such as YAML to JSON. Convert first, then compare.
- "No differences" looks wrong: check whether an ignore setting, a high number tolerance or a duplicate key warning explains it.
- Too many differences: above 100,000 the list stops growing, but the totals stay exact, and the page says the list was truncated.
- A very large list in two different orders: name an id field, or turn on Ignore array order, rather than reading thousands of moves.
The comparison runs on your device, not our servers, so credentials and customer records in a payload are not uploaded to be compared. For a quick overview of how JSON differs from other data formats, see JSON vs CSV vs XML.
Frequently asked questions
How do I compare two JSON files online?
Open the JSON diff tool, drop one file on each side or paste the text, and read the list of added, removed and changed values. It compares as you type. Free covers one pair up to 10 MB per side.
Does it matter if the keys are in a different order?
No. Objects have no order, so a reordered object compares as identical. Only arrays have an order, and you can turn on Ignore array order if that does not matter either.
How do I compare two JSON arrays when the items moved?
Type the name of a unique field, usually id, under Match array items by field. The items then line up by that value instead of by position, so a reordered list shows only the records that really changed. Or turn on Ignore array order.
Can I ignore fields like timestamps?
Yes. List the key names under Keys to ignore, for example updatedAt, requestId. They are skipped at every depth. To skip one location only, use Paths to ignore, which accepts * and ** wildcards.
Can I compare JSON with comments, like a config file?
Yes. Turn on Allow comments and trailing commas, or drop a .jsonc file, which turns it on for you. YAML and XML are not opened directly: convert them to JSON first.
Can I save the differences?
Yes, three ways, all on the free plan: copy a plain summary, download an RFC 6902 JSON Patch, or download a Markdown report. Pro adds batches of up to 50 pairs in one ZIP.