Semantic Diffing of API Schemas
Comparing the published contract between builds and failing the build on a breaking change, so compatibility is mechanical rather than remembered.
Backward compatibility rules are simple and simple to violate: adding an optional field is safe; removing one, renaming one, narrowing a type, adding a required field or tightening validation are not. The difficulty is never knowing the rules — it is noticing at 4 p.m. on a Friday that a change broke one.
A semantic diff makes it a build step. The tool parses both versions of the contract — OpenAPI, Protobuf, Avro, GraphQL SDL — classifies each change as compatible or breaking, and fails the pipeline on the latter unless an explicit major-version marker is present.
Two extensions worth having. Apply the same check to event schemas, where it matters more, because a consumer may read a message written months ago and there is no synchronous error to notice. And record the compatibility mode explicitly in a schema registry — backward, forward or full — since the right answer differs: a queue of long-lived events usually wants full compatibility, an internal RPC usually only needs backward.