JSON Diff & Compare

How to Compare Two JSON Files

Paste the original document into panel A and the changed one into panel B. The comparison runs automatically a moment after you stop typing, and every difference is listed below with the exact path to the value that moved. Nothing is uploaded — parsing and comparison happen in JavaScript in this tab, which is what makes it safe to paste a production API response or a Kubernetes manifest containing internal hostnames.

The output is a list of paths, not a list of lines. $.image.tag tells you precisely which value changed regardless of how either document was indented, in what order its keys were written, or whether one side arrived minified. That is the whole point of comparing JSON structurally instead of textually.

Why a Text Diff Is the Wrong Tool for JSON

Running diff or a side-by-side text comparison on JSON produces two failure modes, and both waste real time.

False positives. Key order is not meaningful in JSON, but it is preserved, so anything that regenerates a document — a serialiser, an export, a Terraform state refresh, a lockfile update — can emit the same data with keys in a different order. A text diff reports every one of those lines as changed. Reformatting from two-space to four-space indentation, or minifying, changes every line in the file while changing nothing at all about the data.

False negatives. Minified JSON is one enormous line. A text diff tells you that line 1 differs from line 1 and shows you 40 kilobytes of characters. The change is in there somewhere.

A structural diff parses both sides first, so formatting and key order stop existing before the comparison starts. Load the built-in example: documents A and B declare service and replicas in opposite orders, and that reordering is correctly reported as no difference at all.

The Four Kinds of Change

Every difference falls into exactly one of these categories, colour-coded in the results.

Separating TYPE from CHANGED is deliberate, because the two mean very different things to whatever consumes the document. A version string moving from 1.4.2 to 1.5.0 is a normal edit. A replica count moving from the number 3 to the string "3" is usually a bug in whatever wrote the file — an environment variable interpolated without a cast, or a YAML round trip that quoted a scalar. It will pass a schema check that only tests presence, and fail at runtime. The example loaded by the button above contains exactly this, so you can see how it is reported.

The Three Options, and When Each Is Right

Ignore array order. Off by default, because array order is data — ["read","write"] and ["write","read"] may well be the same permission set, but the steps in a pipeline definition are certainly not interchangeable. Turn it on when the array is conceptually a set: tags, allowed origins, feature flags, security-group rules. With it on, elements are matched as a multiset, so a moved element is silent while a genuinely duplicated one is still reported.

Treat null as missing. Off by default. Many serialisers disagree about whether an empty field should be omitted or written as null: Jackson omits by default, encoding/json in Go writes null for a nil pointer, and Python's json.dumps writes null for None. Comparing output from two different stacks produces a wall of added-and-removed noise that means nothing. This option collapses it.

Ignore keys. A comma-separated list of key names, matched at any depth. This is the option that turns the tool from interesting into useful: real documents carry fields that change on every write and never matter to a comparison — updatedAt, lastModified, etag, resourceVersion, generation, requestId. Excluding them is usually the difference between a four-line diff you can read and a two-hundred-line one you cannot.

Three Comparisons That Report Nothing

These are not bugs in the tool. They are consequences of parsing JSON into JavaScript values, and they are worth knowing because they are the cases where a diff can genuinely mislead you.

Where JSON Comparison Comes Up

Reviewing an infrastructure change. A Terraform plan, a CloudFormation template, or a Kubernetes manifest rendered before and after a change is the canonical use. Ignore resourceVersion, generation, creationTimestamp, and uid, and what remains is the change you are actually approving.

Debugging an API that changed under you. Capture a response today and a response from before the deploy, and compare. Structural diffing finds the field that was quietly renamed or retyped in seconds, where reading two formatted responses side by side rarely does. If the responses are wrapped in a signed token, our JWT decoder will extract the payload first.

Verifying a migration or a round trip. Convert a document to another format and back, then diff the result against the original. That is the only honest test that a conversion is lossless — and it is how the round-trip guarantees on our JSON to CSV converter and XML to JSON converter were checked. Config written as YAML can be normalised through the YAML to JSON converter first so both sides are directly comparable.

Writing a snapshot test. When a snapshot assertion fails, the framework usually prints a text diff of two pretty-printed blobs. Pasting both sides here, with volatile keys excluded, tells you in one line whether the change is real.

Frequently Asked Questions