The API worked yesterday. Today it doesn't. Nothing in your code changed, so you pull up yesterday's saved response next to today's, put them side by side, and start reading.
Twenty minutes later you are still reading. Both files are four hundred lines long, they look basically identical, and somewhere in there is one field that changed type from a number to a string and quietly broke everything downstream.
This is the wrong way to compare JSON — and almost everyone does it at least once. This guide covers how to diff two JSON files properly: what genuinely counts as a difference, why key order matters in one view but not another, and the array behaviour that trips people up most often.
Why Reading JSON Side by Side Fails
Manual comparison breaks down for three specific reasons, and none of them are about you not paying attention.
Type changes are invisible. A field that returns "age": 28 and later returns "age": "28" looks almost the same on screen. One is a number, the other is a string — and code that does arithmetic on it will now behave very differently.
Formatting noise drowns out real changes. If one file is minified and the other is pretty-printed, every single line looks different even when the data is identical. You end up comparing whitespace instead of data.
Key order is meaningless but distracting. Two JSON objects with the same keys in a different order hold exactly the same data. Your eyes will still flag every displaced line as a change.
What Actually Counts as a Difference in JSON
Before you can trust any diff, you need to know what the JSON specification treats as meaningful. Two rules cover almost every confusing case.
Object key order does not matter
A JSON object is an unordered collection of key–value pairs. These two objects are the same data:
{ "name": "John", "age": 28 }
{ "age": 28, "name": "John" }Any diff tool that matches keys by name will correctly report no difference here. A tool that compares line by line will report several.
Array order does matter
A JSON array is an ordered list. These two are genuinely different values, and a diff tool is right to flag them:
{ "skills": ["JavaScript", "Python"] }
{ "skills": ["Python", "JavaScript"] }This surprises people who think of arrays as "just a set of things". If your API returns results in a non-deterministic order, sort them before comparing — otherwise every comparison will show differences that do not exist.
"count": 5 and "count": "5" look nearly identical but behave completely differently in your code.
Strict, Loose, and Structure Modes
A good comparison tool lets you choose how strictly to compare. The CodBolt JSON Compare tool offers three modes, and picking the right one is most of the work.
Strict — exact match
Every value must match exactly. 28 and 29 are different. "USA" and "Canada" are different. 28 and "28" are different, because one is a number and one is a string. This is the mode you want most of the time.
Loose — ignore formatting
Whitespace differences inside values are ignored. Useful when one source pads its values with extra spacing that you do not consider meaningful. Note the trade-off: because whitespace is stripped before comparison, "John Doe" and "JohnDoe" are treated as equal in this mode. That is helpful for messy data and misleading for clean data, so use it deliberately.
Structure only — shape, not values
Values are ignored entirely; only the shape is compared. For a plain field that means its type: "age": 28 and "age": 29 are identical because both are numbers, while "age": 28 and "age": "28" are flagged because the type changed. For a field holding an object, the shape is its set of keys; for an array, its length.
Use it to confirm an API still returns the same fields with the same types at the top level. One thing to know: because it compares a nested object by its keys rather than by the types inside it, a type change buried deep in the response will not show up here — Strict is the mode that surfaces those.
| Mode | Compares values? | Detects type changes? | Best for |
|---|---|---|---|
| Strict | Yes | Yes | Everyday comparison, exact review |
| Loose | Yes | Yes | Messy data with inconsistent spacing |
| Structure | No | Top level only | API schema and contract checks |
Three Ways to View the Differences
Finding the differences is half the job. Reading them is the other half, and the right view depends on what you are looking for.
Side-by-Side
Both documents in two columns, with differing lines highlighted — red on the left, green on the right. Best for a visual scan when the two files have a similar layout.
Two things are worth knowing about this view. First, it compares the documents line by line, so if the two files list their keys in a different order — or one has an extra field near the top — everything after that point shifts and gets marked as changed. Second, it is a literal text comparison, so the Strict / Loose / Structure setting does not apply here; those modes shape the Unified Diff and Tree View results. When either limitation gets in your way, switch views.
Unified Diff
A summary count at the top, then every change grouped into Removed, Added, and Modified — each with the key name and, for modifications, both the old and new value. This view matches keys by name, so key order does not affect it. This is the view to use when you need a precise list of what changed.
Tree View
The same three groups, but showing only the changed key names without values. Best for a fast overview of a large file when you want to know which fields changed before drilling into how.
How to Compare Two JSON Files, Step by Step
- Open the JSON Compare tool.
- Paste your original JSON into the left editor (JSON 1) and the version you are comparing against into the right one (JSON 2). To load files instead, click Upload and select up to two
.jsonfiles at once — the first fills JSON 1, the second fills JSON 2. Each file can be up to 100 MB. - Choose your Compare mode — Strict, Loose, or Structure Only.
- Choose your View — Side-by-Side, Unified Diff, or Tree View.
- Click Compare. The results appear below with the differences highlighted.
- Use Copy to put the result on your clipboard, or Download to save it as a
json-diff-report.txtfile you can attach to a bug report.
If you just want to see how the output looks before using your own data, click Sample — it loads two example objects that differ in a few fields.
Everything runs inside your browser. Your JSON is never uploaded to a server, which matters when the file you are debugging contains customer data or API keys.
Where JSON Diffing Saves Real Time
- API regression hunting — Save a known-good response, compare it against the current one after a deploy, and the breaking change shows up in seconds instead of an afternoon.
- Config drift between environments — Staging works, production doesn't. Diff the two config files and the missing or mistyped setting surfaces immediately.
- Verifying a schema change — Before shipping a version bump, run Structure Only against the previous response to confirm the top-level fields and their types are unchanged, then run Strict to catch anything deeper.
- Reviewing generated files — Lock files, translation bundles, and exported settings are painful to review in a pull request. A structured diff makes the actual change obvious — and when the file needs a non-developer's eyes, converting it to CSV puts it in a spreadsheet they can actually read.
The pattern in all four is the same: you already suspect something changed, and you need to know exactly what. That is a question a diff answers in seconds and your eyes answer in twenty minutes — if at all.