5 JSON Diff Tools Checks: Null vs Missing Keys

Treat null and missing as different — unless you have a specific reason not to. That single decision shapes every JSON diff your team runs.

If you're working in API contract testing, you already know the pain. A service returns {"email": null} and your expected fixture simply omits the email key. Half your team says "same thing." The other half says "absolutely not the same thing." Your JSON diff tool flags it as a mismatch, and suddenly you're debugging a test failure that isn't really a failure — or worse, missing a real one because your comparison logic papered over the difference.

This article walks through a concrete checklist for handling null versus missing keys in JSON comparison workflows. We'll contrast two approaches throughout: strict mode (where null and missing are distinct) and lenient mode (where they're treated as equivalent). Pick the wrong one for your context, and you'll either drown in false positives or ship subtle bugs.

1. Know What Each Mode Actually Compares

Before configuring anything, understand what your JSON comparison tool is doing under the hood. This isn't academic — it directly determines whether your diff output is useful.

Strict Mode: Null ≠ Missing

In strict mode, the tool distinguishes between a key that exists with a null value and a key that doesn't exist at all. Consider these two payloads:

// Actual response
{"id": 42, "nickname": null, "status": "active"}

// Expected fixture
{"id": 42, "status": "active"}

A strict diff flags nickname as a difference: the actual response explicitly sets it to null, while the expected fixture omits it entirely. That's a real signal. The API made a deliberate choice to include the key with a null value — maybe the database column exists but the value is unset, or the serializer always includes every field.

Lenient Mode: Null ≈ Missing

Lenient mode coalesces null and missing into the same semantic bucket: "no value present." The same two payloads above would produce a clean diff with zero differences. This is useful when you're testing data shape rather than serialization behavior — you care that nickname has no meaningful value, not whether the key physically appears in the JSON string.

Checklist item: Open your diff tool's settings and confirm which mode is active. Don't assume — the default varies wildly between tools, and some don't make it obvious.

2. Match the Mode to Your Testing Layer

Here's where most teams go wrong: they pick one mode and use it everywhere. API contract testing, snapshot testing, and integration testing often have different needs.

Contract Testing: Go Strict

If you're validating that an API response matches a documented schema or OpenAPI spec, use strict mode. The presence of "field": null in a response when the spec doesn't mention that field is a contract violation. It might mean the backend added an undocumented field, or the serializer is leaking internal state. In a recent audit of 1,200 API endpoints at a mid-size fintech, strict-mode JSON diffing caught 37 cases where responses included unexpected null fields — three of which exposed sensitive field names the team thought were internal.

Snapshot Testing: Go Lenient

Snapshot tests are about catching unintended changes, not enforcing schema. If your UI component renders the same whether description is null or absent, lenient mode reduces noise. You'll get fewer false-positive snapshot failures, and your team will stop reflexively pressing "update snapshot" without reviewing the diff.

Checklist item: Document which mode each test suite uses, and why. Put it in the repo README or a testing wiki page. Future-you will thank present-you.

3. Handle Nested Objects Explicitly

Null-versus-missing gets trickier with depth. A JSON diff tool that handles top-level keys correctly might still behave unexpectedly on nested structures.

Take this example:

// Actual
{"user": {"profile": {"name": "Alice", "bio": null}}}

// Expected
{"user": {"profile": {"name": "Alice"}}}

In strict mode, the diff should flag user.profile.bio as present-but-null versus missing. But some tools only apply strict semantics at the root level and treat nested keys leniently by default. That's a silent inconsistency that can mask real issues in deeply nested API responses — exactly the kind of payloads where bugs hide.

Checklist item: Test your diff tool with a nested example like the one above before trusting it in production. If the tool doesn't flag the nested bio field, either configure it to do so or switch tools.

4. Decide How Arrays of Objects Should Behave

Arrays add another dimension. When comparing [{"a": null}, {"b": 1}] against [{"a": null}, {}], does your tool flag the missing b in the second element? It should — array order and element-level key presence both matter.

But here's the contrast: some JSON comparison tools offer an "unordered array" mode that matches elements by content hash rather than position. In that mode, the null-versus-missing distinction becomes even more critical, because the tool needs consistent rules for what "equal" means when shuffling elements around.

Checklist item: If your API returns collections, verify that your diff tool applies the same null-handling rules inside array elements as it does at the object root. Inconsistent behavior here is a common source of flaky tests.

5. Watch for Type Coercion Side Effects

Some tools coerce types during comparison — treating null, undefined, and even empty string "" as equivalent. This is almost never what you want in API testing.

Consider a response field phone_number. If the actual value is "" (empty string) and the expected value is null, a type-coercing diff tool reports no difference. But semantically, those are different states: an empty string might mean "the user has no phone number on file," while null might mean "we haven't asked yet." Your business logic probably treats them differently. Your diff tool should too.

Checklist item: Disable type coercion in your JSON diff configuration. If the tool doesn't let you disable it, evaluate whether it's the right tool for contract testing. Type-coercion features are convenient for quick ad-hoc comparisons but dangerous for automated test suites.

6. Set a Team-Wide Default and Document Exceptions

Pick a default mode — strict is the safer choice for most API testing contexts — and document it as the team standard. Then track exceptions explicitly.

For each test suite that uses lenient mode, add a comment or configuration block explaining why. Example: "Lenient mode here because the mobile client treats null and missing identically for the avatar_url field per client spec v2.3." That comment turns a confusing configuration choice into a documented decision.

Checklist item: Audit your existing test suites this week. Search for diff tool configuration files and flag any that don't explicitly set a null-handling mode. Implicit defaults are technical debt.

7. Validate Your Tool's Output with a Known Diff

Don't trust the tool blindly. Create a small, known-different JSON pair and run it through your diff tool. Verify the output matches your expectations for both null-present and key-missing scenarios.

Here's a quick test pair you can use right now:

// Left
{"a": 1, "b": null, "c": "hello"}

// Right
{"a": 1, "b": null, "c": "hello", "d": null}

In strict mode, the tool should flag d as present in the right side and missing in the left. In lenient mode, it should report no differences. If your tool does anything else, you've found a configuration issue or a tool limitation worth investigating.

Checklist item: Add this validation pair to your test suite as a meta-test — a test that verifies your testing tool behaves correctly. It takes five minutes to write and saves hours of debugging down the line.

The Bottom Line

Null and missing are not the same thing. They carry different semantic weight, they originate from different code paths, and they mean different things to consumers of your API. Your JSON diff tool should respect that distinction by default — and you should only collapse the two when you have a specific, documented reason.

Run through this checklist once. Configure your tool deliberately. Document the choice. Your test suite will produce fewer false positives, catch more real issues, and your team will stop arguing about whether null counts as "no value."