Why comparing JSON is trickier than it looks
JSON (JavaScript Object Notation) is a text format, so at first glance comparing two JSON files should be no different from comparing any two text files. In practice, several things make it deceptive.
The same data can be written many different ways. { "a": 1, "b": 2 } and { "b": 2, "a": 1 } represent the same object, but as raw text they are different — the keys are in a different order. One file might use two-space indentation, another might be minified onto a single line. One might have a trailing newline, another might not. A plain text diff will flag all of these as differences even though the underlying data is identical.
This is why "the two files look the same but the diff shows everything changed" is the single most common frustration people hit when comparing JSON.
Step one: format (pretty-print) both files the same way
Before comparing, put both JSON files into the same shape. The goal is one key or value per line with consistent indentation, so that a line-by-line diff highlights only the values that genuinely changed.
If one of your files is minified (everything on one line), a line diff is almost useless — the entire file is a single line, so the tool can only tell you "line 1 changed." Pretty-print it first. Most code editors do this: in VS Code, open the file and run Format Document (Shift+Alt+F). Online JSON formatters do the same in one click.
Once both files are pretty-printed with the same indentation, paste them into the Text & Code Difference Checker, set the language to JSON for syntax highlighting, and compare. Now the diff shows you the specific lines — and therefore the specific keys and values — that differ.
Step two: deal with key order
Even after formatting, two JSON objects can differ only because their keys are listed in a different order. If you care about the data and not the ordering, sort the keys in both files before comparing.
Many formatters have a "sort keys alphabetically" option. In the command line, jq does it cleanly: jq -S . file1.json > sorted1.json and jq -S . file2.json > sorted2.json produces two files with keys sorted the same way, so a diff of the sorted versions shows only real data changes.
If key order actually matters for your use case — for example you are checking whether a serializer produces byte-identical output — then skip the sort and compare the raw formatted files instead. The right choice depends on whether you are comparing data or comparing exact output.
Reading a JSON diff correctly
Once you run the comparison, the removals (red) and additions (green) map directly to changes in your data:
A changed value appears as one red line and one green line at the same key — for example "status": "active" removed and "status": "inactive" added.
An added key appears as a green line with no matching red line. Watch the surrounding commas: adding a key to an object often also adds a comma to the line above it, so you may see two green lines where you expected one.
A removed key is the reverse — a red line with no green partner.
Array changes are the trickiest. Because arrays are ordered, inserting one element near the top shifts every element below it down by one line, and a naive diff can show the whole array as changed. Turn on word or character precision to see that the values themselves did not change — only their position did.
Common JSON comparison problems and fixes
"Every line is different but the data is the same." Different indentation or minification. Pretty-print both files with the same settings and compare again.
"The diff is huge because of one added array item." Ordered arrays shift lines. Confirm with word-level precision, or sort the arrays if order does not matter for your comparison.
"Numbers look different: 1.0 vs 1." JSON does not distinguish these, but as text they differ. If a serializer produced them, that is a real formatting difference; if you only care about the numeric value, normalise both files through the same tool (like jq) first.
"Escaped characters look different." \/ and / are both valid, and unicode can be written as \u0041 or the literal character. Running both files through the same formatter normalises these.
When to use a semantic JSON diff instead
A line-based diff tool is excellent for seeing exactly what text changed, which is what you usually want when reviewing a config file, an API response, or a fixture. But it is fundamentally comparing text, not structure.
If you need a comparison that understands JSON as data — one that reports "the value at users[3].email changed" regardless of formatting or key order — that is called a semantic or structural diff, and dedicated command-line tools like jd or the jq-based approaches above are built for it. The practical workflow for most people is the one in this guide: normalise both files (pretty-print, optionally sort keys), then use a visual line diff to read the changes. It handles the overwhelming majority of real-world JSON comparison tasks without any installation.