Open huge JSON files instantly. Free & private.๐Ÿ”’ Your data never leaves your browser

How to Compare Two JSON Files

You have two versions of a config, two API responses or two exports, and you need to know what changed. A normal text diff often gives a useless answer for JSON: it flags hundreds of lines when only one value changed. This guide shows why, and how to compare JSON the right way: by structure.

Why text diff fails on JSON

These two documents contain exactly the same data:

{"name":"app","version":"1.0","limits":{"users":10}}
{
  "version": "1.0",
  "limits": { "users": 10 },
  "name": "app"
}

A text diff reports every line as changed, because the formatting and key order differ. Neither matters in JSON: object keys have no order. You want a diff that compares values, not characters.

Structural diff: compare the data

A structural diff parses both documents and walks through them, reporting only real differences, each with its exact path:

CHANGED  $.version          "1.0.0" โ†’ "1.1.0"
ADDED    $.features[2]      "export"
CHANGED  $.limits.users     10 โ†’ 25
REMOVED  $.limits.storage   "5GB"
ADDED    $.beta             true

That is what JSON Diff does. Paste the original on the left and the new version on the right, and it lists every added, removed and changed value with counts. Formatting and key order are ignored.

Try it: JSON DiffCompare two JSON documents and see only the real changes.
Open JSON Diff โ†’

The tricky part: arrays

Arrays do have an order, so they are compared position by position. That is correct for most data, but it has one consequence: if an item is inserted at the start of a list, every following item appears "changed", because each one moved one position.

When the order of a list doesn't matter, sort both lists by a stable key (such as an ID) before comparing. With jq:

jq '.users |= sort_by(.id)' old.json > old.sorted.json
jq '.users |= sort_by(.id)' new.json > new.sorted.json

Command line: jq + diff

jq can normalize both files: -S sorts keys, and formatting becomes identical. Then any regular diff tool works:

diff <(jq -S . old.json) <(jq -S . new.json)

# or with git's colored, word-level diff
git diff --no-index --word-diff <(jq -S . old.json) <(jq -S . new.json)

This is a good choice for scripts and CI pipelines. The output shows lines rather than paths, but the noise from formatting and key order is gone.

In code

Checking whether two documents are equal is built in:

import { isDeepStrictEqual } from 'node:util'

isDeepStrictEqual(JSON.parse(a), JSON.parse(b)) // true/false, key order ignored
import json

json.loads(a) == json.loads(b)   # dict key order ignored, list order matters

To list the differences, use a library such as deepdiff for Python, or jsondiffpatch or microdiff for JavaScript.

Common uses

  • API changes: compare a response before and after a deployment to catch removed or renamed fields.
  • Config drift: compare the staging and production configs.
  • Test failures: see exactly which field differs between the expected and actual output.
  • Data exports: find which records changed between two days.
๐Ÿ’ก Comparing big files? Open each in the JSON Viewer first to find the section you care about, copy that part, and compare only that. It is faster and the result is easier to read.

Related

Tools used in this guide

More guides