Your pull request adds one field to a company response. The diff is additive, the validator is green, nothing was renamed, nothing changed type. Three days later a customer's nightly job starts dropping rows, and the support thread opens with the sentence every API team dreads: it worked before your deploy.

That gap between "the schema still passes" and "nothing broke" is the whole subject of JSON Schema backward compatibility. A schema declares which documents are valid. The code that reads those documents carries a second, unwritten set of assumptions about which values and fields it will see. The two can disagree while both are technically correct.

The rules are mechanical once you know which keyword decides each outcome. Every change has a direction, and every direction has a party it affects.

Table of Contents

Safe and Breaking Schema Changes at a Glance

Most schema changes proposed in a real review fall into a small set of patterns. Here's the verdict for each one, keyed to whether previously valid documents still pass.

Change Old documents still pass Risk to consumers Verdict
Add optional property Yes Low in open models, high in closed models Safe
Add required property No Old documents that omit it fail Breaking
Remove optional property Yes Consumers that read the field may break Usually safe for validation
Remove required property Yes Consumers depending on the field may break Relaxes validation
Make optional property required No Documents without it fail Breaking
Make required property optional Yes None for validation Safe
Narrow type from number to integer No Decimal values fail Breaking
Widen type from integer to number Yes Consumers may get unexpected decimals Safe for validation
Remove enum value No Documents using it fail Breaking
Add enum value Yes Strict code may reject unknown values Safe for validators, risky for code
Tighten pattern, length or numeric bound No Previously valid values fail Breaking
Add property to closed model (additionalProperties false) Yes Old readers reject the new field Breaking for closed consumers
Tighten array constraints (minItems, maxItems, uniqueItems) No Previously valid arrays fail Breaking
Remove union branch (oneOf, anyOf) No Documents matching only that branch fail Breaking

Two rows catch teams out most often. Adding an enum value sails through every validator and still crashes a client whose model maps the enum to a closed set of cases. Adding a property to a closed model breaks any reader that declared additionalProperties: false, because that older schema treats the new field as unknown. Both get described as additive in the review notes. Neither is additive in production.

The rule underneath the table is short. If the new schema still accepts every document the old one accepted, the change is backward compatible at the validator level. Confluent's schema evolution guidance frames this as a language-inclusion problem: the new accepted instance set should contain every previously valid instance, unless all producers and consumers upgrade together.

Comparing two schemas by property name answers a different question from the one you asked. When the shape itself needs to carry more information, this walkthrough of an API design example shows how to keep additions legible to clients that only know the old contract.

Backward Compatibility Beyond the Validator

Say a payments API stores amounts as JSON numbers, and a team decides fractional cents cause more trouble than they're worth. The schema changes so amount must be an integer. The property name is identical, the path is identical, and the diff shows one changed word. Every stored transaction containing 10.5 now fails validation, and every producer still writing 10.5 starts generating invalid documents.

The practical test isn't whether the new schema validates new payloads. It's whether the new schema still accepts every document the old one accepted, and whether existing producers can still generate documents that satisfy it. The JSON Schema evolution guidance from StreamNative makes the same point in sharper terms: compatibility is usually treated as a single property when it's really a relationship between existing documents, producers and consumers.

A diagram illustrating how old intake forms are processed into new, updated forms ensuring backward compatibility.

Think of a paper intake form. A revised version has to accept every completed form the old version accepted, or the office drowns in rejected paperwork. That's the validator rule. But the clerk reading the form also has to understand every field the old clerk understood, which is a different requirement entirely.

Why a diff proves less than it looks

A schema diff compares names, types and required lists. It doesn't compare accepted document sets, and it can't see your client models. Two schemas with identical property names can accept completely different sets of documents, as the number to integer change shows.

The gap widens once you separate three layers that people merge into one word:

  • Validator compatibility: the JSON Schema implementation accepts the document.
  • Deserialization compatibility: your client library maps the payload into a typed model without throwing.
  • Business-logic compatibility: the code downstream interprets the values the way it did before.

The layer where enums break

Deserialization is where enums do their damage. A company endpoint adds a new headcount band, say 1001-5000. The validator passes, because the value is a valid member of an enlarged enum. A strict SDK model generated from the old schema throws on the unknown case, and a sales dashboard that maps only the original bands renders a blank cell.

Nobody filed a bug, because no error surfaced at the API layer. Silent omission is the worst failure mode available.

Practical rule: ship new enum values as a versioned change, or require consumers to handle unknown values by default. One of those two, decided in advance.

Schema diff tools only check the first layer. Consumer contract tests, which load real sample responses into each client model, are what catches the other two. For every change, the first question is which documents and which parties this touches, not whether the diff is additive.

How Required and Optional Fields Decide Compatibility

Object rules decide most outcomes, and one keyword does most of the deciding. Start with whether the model is open or closed. In an open model, additionalProperties defaults to true, so unknown fields are accepted and old readers ignore them. In a closed model, additionalProperties is false, and the older schema rejects a new field as unknown.

That single difference changes the rollout cost of the same change. In an open model, adding an optional property is typically safe: existing instances stay valid and old readers ignore the newcomer. In a closed model, the same addition needs coordinated schema updates, because the older contract is actively hostile to the field.

Direction rule: optional to required restricts; required to optional relaxes. Everything else follows from which direction the accepted set moves.

Properties are optional unless their names appear in the required array, and the JSON Schema object reference spells out the mechanics: required takes an array of zero or more unique property names. A new property therefore stays optional until someone adds it to required, which is the exact moment it becomes breaking. That reference also notes a cross-draft wrinkle worth knowing: Draft 4 required at least one string in the array, while later drafts permit an empty one, so a schema legal under a newer draft can be illegal under Draft 4.

The content-model rules for schema registries trace the same outcomes from validation mechanics rather than syntax: adding a required property breaks previously valid instances that omit it, removing one broadens the valid set, and compatibility testing has to validate representative old documents against the candidate schema.

Extending a base schema without redeclaring it

Draft 2020-12 offers a cleaner route for composed schemas. The 2020-12 specification introduces unevaluatedProperties, which considers annotation results from related applicators and in-place subschemas, not just properties and patternProperties in the same subschema. A base schema defines the known fields, an extension adds its own through allOf, and the final schema still rejects unknown properties without forcing every inherited field to be redeclared.

Publishing a human-readable field reference alongside the schema pays off for the same reason. Akinda's stock screener API field documentation is a useful model: describe each field once, in one place, so an added value or a renamed key shows up as a documentation edit rather than a support ticket.

The testing rule closes the loop. Validate representative old documents against the candidate schema before release, not the reverse.

Dialect Changes That Break Schemas Without New Fields

A library bump is enough. The payload is unchanged, no property was added or renamed, and yesterday's document fails today's validator. Or it still passes, and the service that reads it throws.

Draft 2019-09 and Draft 2020-12 use different keywords to decide what a document means. The field list can be identical. The rules that interpret it are not. Compatibility here is three contracts at once: documents already stored have to stay valid, producers have to know what they may emit, and consumers have to keep reading the values their code expects. A validator that accepts a payload proves only the first of those.

Draft 2019-09 form Draft 2020-12 form Compatibility effect
$recursiveRef $dynamicRef Recursive references can resolve differently
$recursiveAnchor $dynamicAnchor Anchor lookup follows the new keyword rules
Array-form items prefixItems Tuple positions are validated by a different keyword
additionalItems Removed, with items covering the remaining elements Schemas written for old tuple rules validate differently
Single format keyword format-annotation and format-assertion vocabularies Format may be informational in one validator and enforced in another
Media-type schema parameter Dropped Tooling that reads the parameter breaks
$id in a subschema as base URI change $id identifies an embedded schema Reference resolution can change
OpenAPI 3.0 nullable type including null (OpenAPI 3.1) Migration becomes a tooling task

The gap between those drafts is why neighboring services disagree. Draft 2019-09 was published on September 17, 2019, according to the 2019-09 specification. Draft 2020-12 followed roughly three years later. Anything shipped in that stretch was written against whichever dialect the chosen validator implemented.

The three changes that break validation most

Recursive references. $recursiveRef and $recursiveAnchor became $dynamicRef and $dynamicAnchor. A validator that does not know the old keywords does not raise a clear error. It applies a different resolution rule. A recursive schema can then accept a tree the producer never meant to send, and strict consumer code that walks a bounded structure follows a reference that no longer points where it used to.

Tuples. Array-form items became prefixItems. Under 2020-12, items applies to every element after that prefix. Two entries listed under items in a 2019-09 schema described positions. Under the newer rules those same entries do not mean "this array has exactly these two slots."

Removed keywords. additionalItems is gone. Unknown keywords are ignored, so the length cap disappears. The validator accepts any length. Code that reads index 0 and index 1 and assumes nothing follows still compiles, then mishandles the extra elements.

format is split across the format-annotation and format-assertion vocabularies. One validator records that a string looks like a date. Another rejects it. A consumer written against the strict validator was using the schema as a gate. After the dialect change the gate opens, the document is valid, and the parser downstream still cannot read the value. The media-type schema parameter is a smaller version of the same split: the document can validate, while tooling that used to read that parameter no longer has a place to look.

OpenAPI 3.1 aligned with 2020-12 and replaced nullable plus boolean exclusiveMinimum and exclusiveMaximum with JSON Schema forms, as the JSON Schema project's account of this migration describes. Generators, linters, and client code all have to move together, because each one is a consumer of the schema, not just of the JSON.

Working rule: a dialect upgrade rewrites the contracts for stored documents, for producers, and for the code that reads results. Passing validation is only the first contract.

That same discussion of a stable release model aims at long-lived releases that keep strict backward and forward compatibility. Until that model is what your validator runs, the dialect boundary is yours to manage: same fields, different keyword rules, different outcomes for the code that reads the data.

How to Roll Out a Schema Change Safely

A producer adds one field to a live response that already carries a hundred or more attributes. The validator still accepts every document it accepted yesterday. A strict client that set additionalProperties to false rejects the same payload on the next call. The schema change passed, and the integration broke, because three contracts moved at different speeds: documents already stored, the producer that writes them, and each consumer that reads them.

A validator only checks one of those contracts. Code that deserializes into a fixed model checks another. Records written last quarter check a third. Safe rollout is consumer-first, additive evolution, so none of the three has to jump on the same deploy.

A four-step infographic illustrating the safe process for rolling out schema changes in software systems.

Run the change in this order.

  1. Deploy consumers that accept both representations first. Until every reader tolerates the old shape and the new one, a producer change is a gamble you cannot price. Readers go first so later steps have somewhere safe to land.
  2. Add the new field as optional and leave the old field in place. Both fields coexist. No reader has to migrate on the producer's schedule, and documents already stored still validate.
  3. Start emitting the new field during a published deprecation window. The window is the contract consumers plan against. They can see how long the old field will keep arriving.
  4. Watch usage telemetry for reads of the old field. A deprecation date with no read counts is only a calendar entry. Telemetry shows whether anyone still depends on that field.
  5. Remove or constrain the old field only after telemetry confirms migration. This step is irreversible, so it stays last and runs only on evidence.

Shipping the producer before its consumers causes most incidents. Bundling a dialect upgrade into the same release is the next most common failure. When both land together, a broken call no longer tells you whether the field or the dialect rules caused it. Split them.

Schema registries commonly distinguish backward, forward, and full compatibility. Transitive modes test against all historical versions rather than only the immediately preceding one, which is stronger protection for long-lived integrations. A mode the registry accepts can still be too loose for a typed client. Treat that result as one check, not the whole release.

Closed contracts need their own path. When clients set additionalProperties to false, an added server field breaks them even though the field is optional. Offer a versioned contract, or ask those clients to allow unknown properties before you add anything. Routing and policy for that split are covered in this guide to API versioning best practices.

Rules hold only when a gate enforces them. Schema reviews that live in comment threads get skipped when a deadline hits, which is why teams automate merge gates in the pull request workflow rather than trusting memory.

How to Test Compatibility Before Each Release

Compatibility is a routine, not a review meeting. Four steps run before every release, and each one answers a question the others can't.

  1. Generate representative fixtures from production-shaped responses. Include nulls, documents with missing optional fields, and your largest arrays, because empty test data hides every constraint bug.
  2. Validate every fixture against both schemas, the one in production and the candidate.
  3. Fail the release if any document the old schema accepted is rejected by the new one.
  4. Run the same fixtures through each client's model or parser, since a passing validator says nothing about a typed deserializer.

A step-by-step checklist infographic detailing how to ensure API and JSON schema backward compatibility before software releases.

Keep this checklist of edge cases next to your CI notes:

  • Documents with no optional fields present, which is what older stored records usually look like.
  • Unknown enum values, including one your candidate schema adds but no fixture yet contains.
  • Nested objects with additional properties, where a strict reader and a permissive validator disagree.
  • References resolved across files, since resolution behaviour changes with dialects.
  • The oldest dialect you still support, because a schema legal in one draft may be illegal in another.

Report results as a simple table: fixture name, old result, new result, action. A failing row is your release blocker and your regression test at the same time. Keep a fixture set for every released version, so a change compatible with the last release is also checked against the one before it.

The 2020-12 release notes explain why the project publishes migration documents at all: draft-to-draft behaviour can't be presumed interchangeable, because changes reach vocabulary boundaries and document interpretation, not just field lists. A schema diff will still flag a renamed or removed key fast, and you should run it. It cannot prove the accepted set stayed the same, so fixtures remain the final gate.

Fixture sets age like any other test asset. Keeping test case libraries useful after releases is the maintenance discipline that keeps a growing suite from becoming noise. When you add a new pipeline, borrow its shape for fixtures: a contact enrichment pipeline's response typically carries the widest spread of optional attributes, which makes it a good stress case for strict readers.

Confirm Compatibility Before Your Next Schema Release

A producer ships a new company payload on Friday. The validator is green. On Monday a strict consumer throws: it still reads headcount as a required integer, and the new document only sends employee_count. Three contracts decide that release, not one green check.

Existing documents are the first contract. Every payload the old schema accepted has to stay valid. If a formerly legal document now fails, the change needs a version, not a review comment.

Producers are the second contract. They write the JSON. A rename the new schema allows still leaves old writers emitting the previous key. Until those writers move, both shapes have to parse.

Consumers are the third. A passing validator still misleads people here. Validation only asks whether the document is allowed. Deserialization and the business rules after it ask whether the code can read the data. A strict reader that demands a field, a type, or a fixed enum breaks on a change the schema accepts. Contract tests have to pass on both representations.

Release on the planned date only when all three hold and a deprecation window is backed by telemetry. If the old field disappears the same day the new one ships, nobody has exit criteria. Any no means you split the change: add the new field, keep the old one, and remove it after readers have moved.

Fetchin is a B2B data API that turns professional profile and company URLs into structured JSON. Calls return synchronously by default, with asynchronous delivery when a workflow needs it, so you can fit responses into the pipeline you already run. Visit Fetchin to read the response reference and put a live payload into your fixture set.

Write down the current dialect, list every consumer by name, and run that check before anyone deploys the next change.