← Home · Blog

How to Compare Two JSON Files

Published: May 29, 2025 · 5 min read

Comparing JSON documents is a common task when debugging APIs, reviewing config changes, verifying data migrations, or testing. Unlike plain text diff, JSON comparison needs to understand the structure — key order shouldn't matter, and nested changes need to be tracked at every level.

Why Regular Diff Doesn't Work for JSON

Standard text diff tools (like Unix diff) compare line by line. But JSON objects have no defined key order — these two are identical:

{"name": "Alice", "age": 30} {"age": 30, "name": "Alice"}

A text diff would show these as different, but semantically they're the same. You need a structural diff that compares values by their keys, not their position.

Method 1: Online Tool (Fastest)

  1. Go to JSON Compare & Diff
  2. Paste the first JSON in the left panel
  3. Paste the second JSON in the right panel
  4. Click "Compare" — see color-coded results instantly

The tool shows a table with every difference, color-coded: green = added, red = removed, yellow = changed. Each difference shows the exact path (e.g., address.city) so you can find it quickly.

Method 2: Command Line with jq

For quick terminal comparisons:

# Sort keys and compare diff <(jq -S . file1.json) <(jq -S . file2.json) # Or use jd (JSON diff tool) jd file1.json file2.json

Method 3: In JavaScript Code

function deepDiff(obj1, obj2, path = '') { const diffs = []; const allKeys = new Set([ ...Object.keys(obj1 || {}), ...Object.keys(obj2 || {}) ]); for (const key of allKeys) { const fullPath = path ? `${path}.${key}` : key; if (!(key in obj1)) diffs.push({path: fullPath, type: 'added'}); else if (!(key in obj2)) diffs.push({path: fullPath, type: 'removed'}); else if (JSON.stringify(obj1[key]) !== JSON.stringify(obj2[key])) { if (typeof obj1[key] === 'object' && typeof obj2[key] === 'object') { diffs.push(...deepDiff(obj1[key], obj2[key], fullPath)); } else { diffs.push({path: fullPath, type: 'changed', from: obj1[key], to: obj2[key]}); } } } return diffs; }

Types of Differences

  • Added — a key exists in the second file but not the first
  • Removed — a key exists in the first file but not the second
  • Changed — same key exists in both, but values differ
  • Type changed — same key, but type is different (e.g., string → number)
  • Array reordered — same items but in different order

Common Use Cases

  • API versioning — compare responses before and after a deployment
  • Config changes — review what changed in a Kubernetes manifest or package.json
  • Data migration — verify that migrated data matches the source
  • Testing — compare expected vs actual API responses in test suites
  • Code review — understand what a PR changes in JSON config files

Tips for Better Comparisons

  • Format both files with the same indentation before comparing (use our formatter)
  • Sort keys alphabetically if key order differs between sources
  • For large files, use the search/filter in diff output to find specific changes
  • When comparing arrays, be aware that element order matters in JSON

More Articles

5 Common JSON Errors

How to Format JSON

JSON API Best Practices

← All Articles · Home · Privacy Policy