Schema Diff and Change Classifier
Compare two contract versions and surface likely breaking, compatible and review-required changes.
Compare the two versions to classify structural changes.
Compatibility depends on the consumer
A schema diff is meaningful only with a policy. This workbench takes a conservative producer-oriented view: removing a declared property, adding a new required property, changing its type or narrowing an enum is flagged as likely breaking. Additions that remain optional are classified as compatible with a review note.
Turn the diff into a compatibility review
Start by naming the direction under test. A new producer sending documents to an old consumer faces different risks from an old producer sending retained documents to a new consumer. For each flagged component, record whether unknown fields are ignored, whether generated bindings are regenerated, whether default values are materialized and whether downstream code treats enumerations or element order as exhaustive.
Then attach evidence. Keep examples from both releases, an expected classification and results from the actual validators, serializers and consumer versions. Optional additions frequently remain schema-valid while breaking strict deserializers. A broadened type may help producers while violating an assumption in application code. The workbench cannot see those dependencies, so “compatible” means no breaking change was found by the focused comparison—not universal safety.
Published limitations
The JSON mode does not evaluate arbitrary subschemas, conditional keywords or every vocabulary interaction. It does not resolve remote references or select dialect vocabularies. The XSD mode compares selected element declarations in one file and does not resolve a schema set, derive effective content models or evaluate substitution groups. Use the report to focus review, then run complete validators and contract tests in CI.
For a broader strategy, read Data contracts across schema ecosystems.
Frequently asked questions
01What is a breaking schema change?
A breaking change causes at least one previously valid producer or consumer interaction to fail under the chosen compatibility policy. Adding a required property is a common breaking change for existing producers.
02Is adding an optional property always compatible?
It is usually backward-compatible for validators that allow additional properties and consumers that ignore unknown fields. Strict consumers, code generation and closed content models can change that conclusion.
03How does the tool compare JSON Schema?
It compares top-level object properties, required arrays, declared types and enum values. It is a focused structural audit rather than a complete semantic comparison of every JSON Schema vocabulary.
04How does the XSD comparison work?
For XSD input, the tool compares declared element names and basic type and occurrence attributes. It does not resolve imports, includes, substitution groups or derived type semantics.
05Why does compatibility need a direction?
Backward compatibility asks whether new consumers accept old data, while forward compatibility asks whether old consumers accept new data. A change can pass one direction and fail the other.
06Does changing documentation count as breaking?
Changing only an annotation or description is normally non-breaking at validation level, but it may signal changed semantics. Contract review should not ignore semantic documentation changes.
07Can this replace contract tests?
No. A diff identifies likely risk. Contract tests verify behavior against real producer and consumer implementations and should cover representative payloads.
08What should accompany a schema version change?
Publish the new schema, a classified change list, migration instructions, valid and invalid examples, and a clear support window for the previous version.
Define the policy the classifier cannot infer
Decide whether consumers reject unknown properties or elements, whether producers omit absent optional values, and whether numeric or string constraints are interpreted beyond validation. Record how code generators represent unions, enumerations, defaults and nullability. The same structural edit can be compatible for a tolerant document processor and breaking for a generated class with exhaustive cases.
Version direction belongs in the policy. Backward compatibility asks whether the new consumer accepts retained old data; forward compatibility asks whether an old consumer tolerates new producer output. Full bidirectional compatibility requires both exercises. Run the comparison and fixtures in each direction instead of attaching one unqualified label to a release.
Changes that need manual review
Renames, moves and refactors can appear as one removal plus one addition even when a human sees a single conceptual change. Changes to regular expressions, numeric bounds, object closure, element ordering, wildcards, namespace URIs, identity constraints, defaults and annotations may alter behavior without appearing in the focused report. References and composition can also change the effective model while the visible root file barely changes.
For each release, retain the before and after contract, generated report, policy decision and executable consumer evidence. Give every accepted breaking change a migration note and owner. If the team intentionally accepts a warning, explain the consumer behavior that makes it safe so a future reviewer does not have to reconstruct the reasoning from the schema alone.