How To Compare Json

Why text diff fails on JSON

Diffing JSON sounds easy — just run a text diff. But JSON is structured, not lines, so a text diff flags formatting changes and key reorderings as real differences when they aren’t. A proper JSON diff understands objects (order-independent), arrays (order-dependent), and types. This guide covers how JSON diffing works, the gotchas around array matching, numeric precision, missing-vs-null, when text diff is actually the right tool, and how to use diffs in code review, API contract testing, and debugging.

Structural diff basics

Given these two JSON values:

Array diffing is hard

A text diff says they’re different. A JSON diff says they’re identical. Object key order is not semantic in JSON.

Numeric precision gotchas

A JSON diff walks the tree recursively and reports changes in semantic terms:

Missing vs null vs undefined

Object keys are unique; array positions aren’t. If you’ve got:

Viewing the diff

Picking the right strategy depends on what the array represents. Tell the tool which field is the identity, and it does the right thing.

Common use cases

Some APIs treat these identically; some don’t. Your diff tool needs a consistent stance:

When to use text diff instead

Common mistakes

Run the numbers