JSON Schema Backward-Compatibility Diff

How It Works

Two JSON Schemas for a message’s data block — old and new — and a single question: can a consumer that upgraded to the new schema still read messages produced under the old one? If yes, ship it. If no, you version the message identity instead of mutating it. This applies the same rules a backward-compatibility linter would, in your browser.

What counts as breaking

Compatibility is asymmetric — loosening is safe, tightening is not:

• Safe: adding an optional field, dropping a required constraint, widening an enum, relaxing a minimum.
• Breaking: adding a required field (or making an existing one required), removing / renaming / retyping a field, dropping an enum value, raising a minimum or minLength, closing additionalProperties.

A rename is a remove plus an add, so it surfaces as breaking — correctly: a consumer reading the old field name won’t find it.

Why a breaking change means a new URN

You can’t change a distributed contract atomically: producers and consumers deploy independently, and with at-least-once delivery, in-flight messages under the old shape keep arriving while you roll out the new one. So a breaking change means a new identity (orders.created.v2), run in parallel until the old one has no consumers left — never a silent redefinition of the existing one. The longer argument is in Schema Evolution.

The same rules, applied in CI rather than in your browser, are the BabelQueue schema-validation spec — enforced by the bqschema tool in babelqueue-registry.

Privacy

Both schemas are diffed entirely in your browser. Nothing is sent anywhere.