How to Compare JSON Files: JSON Diff, Key Order & Nested Changes

Comparing JSON files by eye is painful. A normal text diff shows every whitespace change, every reordered key, and every formatting difference, even when the data is actually the same. A proper JSON diff understands the structure: objects, arrays, keys, values, and paths. This guide shows how to compare JSON files cleanly online, in JavaScript, and from the command line.

The quickest way: compare JSON online

Paste the old JSON on the left, paste the new JSON on the right, and open the JSON Diff tool. The tool parses both documents, compares the data structure, and shows added, removed, and changed values by path.

Use a client-side JSON compare tool when your files contain API responses, customer data, config secrets, or production payloads. Ours runs in your browser, so your JSON is not uploaded or stored.

Use it when: you want a private, readable comparison without fighting formatting noise.

Structural diff beats text diff

Text diff is useful for code, but JSON is data. These two objects mean the same thing:

{ "id": 1, "name": "Ada" }

{
  "name": "Ada",
  "id": 1
}

A text diff sees many changes because the lines moved. A structural JSON diff sees no data change because object key order does not matter in JSON. That is the main reason to use a JSON-aware compare tool.

What a good JSON diff should show

A useful diff should report changes by path:

• Added values - fields that appear only in the new JSON.
• Removed values - fields that existed before but are missing now.
• Changed values - same path, different value.
• Nested paths - changes like users[2].address.city, not just “line 48”.

Path-based output is easier to act on. It tells you exactly which field changed, even when the JSON has been pretty-printed differently.

Key order, whitespace, and formatting

Whitespace and indentation do not affect JSON values. Neither does object key order. Before comparing, a JSON diff tool should parse both inputs into values, then compare those values. That means:

• minified and pretty JSON compare correctly
• reordered object keys do not create false positives
• line endings and indentation do not matter

If you need stable output before committing a file, run it through a JSON formatter or JSON minifier first.

Arrays are the tricky part

Arrays are ordered in JSON, so [1, 2, 3] and [3, 2, 1] are technically different. But real data sometimes treats arrays like sets, especially for tags, permissions, or IDs.

There are two common modes:

• Order-sensitive diff - best for timelines, ranked results, steps, and anything where position matters.
• Ignore array order - best for tags, scopes, permissions, and unordered lists.

Pick the mode that matches the meaning of your data. Otherwise, you will either miss real changes or create noisy false positives.

Compare JSON in JavaScript

For a simple script, parse both files and compare stable serialized output:

function sortKeys(value) {
  if (Array.isArray(value)) return value.map(sortKeys);
  if (value && typeof value === "object") {
    return Object.fromEntries(
      Object.keys(value)
        .sort()
        .map((key) => [key, sortKeys(value[key])]),
    );
  }
  return value;
}

const same =
  JSON.stringify(sortKeys(JSON.parse(oldJson))) ===
  JSON.stringify(sortKeys(JSON.parse(newJson)));

This is enough to ignore object key order, but it only tells you same vs different. For a useful report, you need to walk both trees and collect changed paths - exactly what the online tool does.

Compare JSON on the command line

For quick checks, normalize both files with jq and use diff:

jq --sort-keys . old.json > old.sorted.json
jq --sort-keys . new.json > new.sorted.json
diff -u old.sorted.json new.sorted.json

This removes formatting and key-order noise, but it still produces a line diff rather than a path-addressed structural report.

Which method should you use?

For quick, private comparisons, use the online JSON Diff tool: paste two documents, compare, and export the diff. Use jq when you are already in a terminal, and write JavaScript when the comparison is part of a test or pipeline.

Need to fix input before comparing? Try JSON Repair, validate syntax with the JSON Validator, or read common JSON errors and how to fix them.