A contract checker for JSON event streams. It reads the schema each producer publishes per topic, decides whether a new version breaks anyone reading the old one, and blocks the pull request before the change ships.
An event stream couples teams who never call each other. Change amount from integer cents to a decimal string, and your own tests pass while a consumer on another team fails to decode. Every breaking verdict here comes with an event that proves it: the old schema accepts it and the new one rejects it.
Plays the six stages below in order, about 70 seconds. Scroll or press Esc to stop.
All three are real runs of schema-drift 0.1.0 on the repo's own examples, output verbatim. The gate session is examples/gate-demo.sh, a pull request against a throwaway git repository, shortened where marked.
schema-drift supports a subset of JSON Schema: the part whose compatibility it can decide exactly. Anything outside it is an error with a JSON Pointer, never skipped.
pattern, $ref, oneOf or OpenAPI's nullable, gets a hint about what to write instead.encoding/json would quietly keep the last one. So are schemas no value can satisfy, and enum values the rest of the schema rejects.The subset is type, enum, properties, required, additionalProperties, items, numeric bounds, string and array lengths, and four formats, which are asserted rather than treated as annotations.
Six schemas the parser refuses Illustrative input
schema-drift check with examples/contracts/orders/v1.json as the other side, and the error lines are printed exactly as they came back.Every compatibility mode comes down to one question: is every event valid under schema A also valid under schema B? Backward asks it with the old schema as the writer, so consumers on the new schema can read old events. Forward asks it the other way round. Full asks both.
additionalProperties, and array items and sizes.* standing for any array item.Which mode you need depends on who upgrades first. Consumers first: backward. Producers first: forward. Either, or old events replayed from a retained topic: full.
The repo's example contracts, pair by pair
| Field | Old | New | Backwardnew consumers, old events | Forwardold consumers, new events |
|---|
examples/contracts; the table restates what each file declares, and the output under it is the real schema-drift check run on that pair, verbatim, with its exit code. Payments is checked with --mode FULL, the mode its topic folder names; the others use the default, BACKWARD.A checker that cries wolf teaches people to ignore it. So for each reason it finds, schema-drift builds a whole event and checks it with its own validator: the writer's schema has to accept it and the reader's has to reject it. Only then is it printed as the e.g. line.
An e.g. event, fed back through verify
Proven: the writer accepts it and the reader rejects it.
e.g. line from the real check output in stage 2, saved to a file and run through schema-drift verify against both schemas. The verify output and exit codes are verbatim.Contracts live in the repository, one folder per topic: v1.json, v2.json and so on, plus an optional mode file. schema-drift gate compares that folder in the working tree with the same folder at the base branch, read from git, and exits 1 on any problem.
_TRANSITIVE mode.vN.json or mode.It reads only git and the working tree. There is no registry to run and nothing to fetch, so the check is one step in the pull request workflow.
Two pull requests against the same main
schema-drift gate --base main
examples/gate-demo.sh, run for real. A safe change is Illustrative input: a pull request written for this page that rewords the title of orders v1 and adds v3 with one new optional field, run through the same command. Output is verbatim, except that the e.g. lines are left out here; stage 3 shows what they prove.MergedAbove this line the contract change is still a pull request. Below it the schema is published, producers write events under it, and consumers on other teams decode them.
A contract only protects consumers if producers actually honour it. schema-drift verify reads newline-delimited JSON events you've captured and reports every problem at its JSON Pointer, with the line it came from.
"not-a-uuid" is not a uuid and "yesterday" is not a date-time.1.0 is an integer, and enum values compare by value.encoding/json would.verify checks samples you capture. It doesn't watch a live topic or talk to a broker.
Five captured events against orders v2
examples/events/orders-mixed.ndjson, and the problems under each are the real output of schema-drift verify examples/contracts/orders/v2.json on that file, line for line.The repo ships an ordinary Go consumer written against orders v2: it decodes each event into a struct and adds up revenue per currency. It is what stage 4 protects, and what happens when nothing does.
amount is now a string and its struct field is an int64.verify before any consumer sees it, and by gate before v3 is ever published.Semantics stay invisible. If amount kept type integer and changed from cents to dollars, every check would pass. A schema can only carry what it states.
One consumer, two producers, one check
examples/consumer built with go build, fed the repo's examples/events/orders-v2.ndjson and orders-v3.ndjson, then schema-drift verify on the v3 events. Output and exit codes are verbatim.A compatibility checker can be wrong in two directions, and both are tested against the validator as an independent oracle. The numbers are from the default test run, read from the test log.
The dangerous mistake. TestSoundness generates random schema pairs, most of them by mutating one schema into the next the way people edit contracts. For every pair judged compatible, it generates events valid under the writer and checks each against the reader.
The noisy mistake, the one that teaches people to ignore a tool. TestEveryBreakIsProven fails on any reason whose witness the validator doesn't confirm on both sides.
The README lists real fixes these two tests forced:
{"minLength": 0} was treated as a constraint.Counted with go test -v ./...: 29 tests, all passing, no subtests. No network, and the gate tests build real git repositories in temporary directories.
/ and ~, 1.0 as an integer, nullable type lists, each format, enum equality by value.CI runs vet, gofmt, the short suite under the race detector and the full suite on Go 1.22 and the current stable release, plus a job that regenerates the README's quoted output and fails on any difference.
$ref, oneOf, pattern and friendsoneOf. Split the topic, or use one schema with the union of fields.infergit clone https://github.com/ahmed-hashim-pro/schema-drift
cd schema-drift
go build -o schema-drift ./cmd/schema-drift
./schema-drift check examples/contracts/orders/v2.json examples/contracts/orders/v3.json
./schema-drift history examples/contracts
./schema-drift verify examples/contracts/orders/v2.json examples/events/orders-mixed.ndjson
./schema-drift infer examples/events/orders-v2.ndjson
# A pull request, as CI sees it
SCHEMA_DRIFT=$PWD/schema-drift examples/gate-demo.sh
go test ./...
Go 1.22 or newer, no dependencies outside the standard library. In CI it is one step: schema-drift gate --base origin/main after a checkout with full history.