How to compare two JSON files

Two files can look different and be equal, or look equal and differ in one nested key. Here are three ways to compare JSON that do not lie to you, plus the traps that produce differences out of thin air.

First, know what you are comparing

A JSON document is a tree of objects, arrays, strings, numbers, booleans and null. Two documents are equal when the trees match, not when the text matches. That single sentence explains most confusion in JSON diffing: the text can differ wildly while the data is identical, and two near-identical texts can hide a data change. Every method below is really a way of getting from text to tree without losing anything on the way.

Method 1: normalize both files, then diff (fastest for a one-off check)

Pretty-print each file. Paste it into the JSON Formatter, or run jq '.' file.json on the command line. This removes indentation and whitespace noise
Sort object keys recursively: jq -S '.' file.json. Now identical data looks identical, regardless of the order keys appeared in
Diff the two outputs: paste them into any text diff tool, or run git diff --no-index a-normalized.json b-normalized.json. What remains is real

The JSON Formatter runs entirely in your browser, so unshareable JSON (config with tokens, private payloads) never leaves your machine.

Method 2: use an online JSON diff checker

Dedicated checkers take both files and render a tree with additions, removals and changes marked. They save you the normalize step, which matters when you compare JSON often. A good one does three things: it is type-aware (it flags 1 vs "1" instead of shrugging), it treats arrays as ordered, and it distinguishes a missing key from a null value.

We are building one for this site. Until it ships, Method 1 with the JSON Formatter plus any text diff gets you the same answer.

Method 3: git diff, when the files live in a repo

For API responses and config files tracked in git, commit the normalized form and let code review do the diffing: git diff then shows only value changes between versions. If the JSON is machine-generated and you cannot commit normalized copies, pipe both sides through jq -S into temporary files first. The extra ten seconds is what stands between you and a review thread about whitespace.

The differences that are not differences

These show up as changes in almost every naive comparison. None of them is a data change:

Formatting and indentation. Pretty-printed vs compact changes nothing about the data. A diff that counts this counts nothing.
Key order inside objects. {"a":1,"b":2} equals {"b":2,"a":1}. Object order is not part of the data model.
Unicode escapes. "\u0041" and "A" are the same string written two ways.
Number spelling. 1 and 1.0 are the same JSON number; a checker that treats them as different values is comparing text, not data.

And one trap in the other direction: array order is real. [1,2] and [2,1] are different values. If a tool sorts arrays before comparing to quieten object-order noise, it also hides genuine reorderings. Know which behavior your checker has.

Two related near-misses worth memorizing: 1 and "1" are different types (number vs string), and {"a":null} is a different document from {}. Most real bugs found while diffing JSON are one of these two.

Frequently Asked Questions

Is key order significant in JSON?

Not inside objects. The objects {"a":1,"b":2} and {"b":2,"a":1} are equal as JSON values, so a comparison that flags them as different is reporting formatting, not data. Arrays are the exception: their order is part of the data, so [1,2] and [2,1] really are different.

How do I compare two JSON files in git?

Normalize both files first, then diff. Run each through jq -S '.' to sort keys and pretty-print, and git diff --no-index a.json b.json will then show only real value changes instead of whitespace noise.

What is the fastest way to compare two JSON files?

Pretty-print both files with their keys sorted, then run any text diff over the results. For one-off checks, paste each file into a JSON formatter and eyeball; for repeated checks, use a dedicated JSON diff checker that understands types and array order.