Every rule Driftwatch uses to call a change breaking, and exactly which changes publish without a person reading them first.
Severity is deterministic
Every change is classified by a fixed rule, not by a language model. The same pair of specs always produces the same severities, so a wrong call is a bug in a rule that can be found and fixed, rather than an unreproducible generation.
A model is used for one thing only: rewriting explanatory prose where the templates read thin. It never assigns severity, and it never sets the headline.
The three direction flips
Producer-side tools ask “does this break my callers?” This feed sits on the calling end, where three rules invert. They are the reason it exists.
A response property becoming optional is safe for a producer and a null dereference waiting to happen for you.
A new enum value in a response is additive for a producer. It breaks exhaustive switches, strict parsers and generated client enums.
A removed request parameter raises no error at all. The provider ignores it, your results change, and nothing goes red.
What we are actually reading
Specifications, not behaviour. Some providers update their spec weeks after shipping, and some never do. Everything here is spec-derived, and a change that never reached the spec will never reach this feed.
Shared schemas are diffed once each, not once per endpoint that references them, and the number of operations a component reaches is shown alongside it. Following references inline instead produced 4528 “breaking” changes for a single Stripe release, the same enum reported 2319 times.
What publishes without a person
A change below 85 confidence never reaches the feed, and cosmetic changes never do at any confidence. Precision over recall, without apology: one false breaking change costs a reader permanently.
Above that line, a person used to approve every change. Nearly all of them turned out to be the same few shapes, checked against the real specs many times over, so those now publish on their own. Every false alarm found so far came from a handful of other shapes, and those still wait for a person:
Endpoint or operation removed (path.removed, path.moved, operation.removed). Providers withdraw endpoints they documented early and move others into separate spec files, and both look exactly like a removal.
Any authentication change. A spec converter once wrote a malformed security entry that read as a new auth scheme.
Everything in an unusually large release: more than 25 breaking changes and more than 4× that API’s typical release. Format migrations look like this, and so do real overhauls worth a second look.
The first changes from a newly added API, until a person has read them once.
Each published change records whether a person or the policy (auto-1) published it.
The ruleset
Rule
Severity
What it does to calling code
operation.removed
Breaking
This verb now 405s. The path still resolves, so a health check on the URL will not catch it.
path.moved
Breaking
The same operations are now documented at a new path. Requests to the old one may 404, so update the URL; anything else that changed at the new path is listed separately.
path.removed
Breaking
Requests to this path now 404.
request.enum.value-removed
Breaking
A value you may have hardcoded is now rejected.
request.param.became-required
Breaking
Calls that omit it are rejected.
request.param.removed ⇄
Breaking
No error is raised. The value is ignored and your results change silently, which is the hardest class of break to notice.
request.param.required-added
Breaking
Every existing call that omits it is rejected.
request.property.became-required
Breaking
Partial payloads are rejected.
request.property.removed ⇄
Breaking
Usually ignored rather than rejected, so the call succeeds and does something subtly different.
request.property.type-changed
Breaking
Serialization mismatch. Integer-to-string moves are the usual cause and the usual outage.
response.enum.constraint-removed ⇄
Breaking
The documented set of values is gone, so anything can appear. Every exhaustive switch and generated enum over this field is now incomplete.
response.enum.value-added ⇄
Breaking
Producer-side tools call this additive. It breaks exhaustive switches, strict parsers and generated client enums.
response.property.became-optional ⇄
Breaking
Producer-side tools call this non-breaking. For a consumer it is a null dereference on an unknown future date.
response.property.removed
Breaking
Reads of this field return undefined, and the failure surfaces wherever that value is used rather than at the call.
response.property.type-changed
Breaking
Parse failure, or silent coercion depending on your client.
security.alternative-removed
Breaking
Callers using the withdrawn credentials are rejected. Callers already on a remaining option are unaffected.
security.scheme-changed
Breaking
The integration needs reworking, not patching.
security.scope-added
Breaking
Existing tokens 403. This needs user re-consent, not a code change, so it cannot be fixed by deploying.
operation.deprecated
Deprecation
Still works today. This is the earliest warning you will get before it is removed.
default.value-changed
Behavioral
Behavior shifts for every call that omits the field.
pagination.default-changed
Behavioral
Silent truncation. Code that does not paginate keeps working and quietly returns a different slice of the data.
response.property.now-always-null
Behavioral
Nothing throws, since the field could already be null, but the value you read here is gone. Often a spec-generator artifact, so it is held for a person to check.
response.property.optional-now-nullable
Behavioral
The field was never guaranteed, so code already handles it missing. Code that checks only for undefined, not null, will now see null.
response.status-code.added
Behavioral
An unhandled branch in your error handling.
response.status-code.removed
Behavioral
Dead branch, or an undocumented response you still receive.
schema.composition-changed
Behavioral
The set of shapes this value can take changed. Worth a look, but the structural diff cannot say precisely how.
schema.property-narrowed-to-variants
Behavioral
The schema became a set of variants and only some keep this field. Calls using it on the variants it was documented for are unaffected; elsewhere it may now be ignored or rejected.
schema.ref-retargeted
Behavioral
Often a rename with an identical shape, sometimes a genuine retype. The structural diff cannot tell which, so this is held below the publish threshold on purpose.
security.requirement-removed
Behavioral
The operation no longer demands this credential.
operation.added
Additive
No action needed.
operation.undeprecated
Additive
The operation is supported again.
path.added
Additive
No action needed.
request.enum.constraint-removed
Additive
A relaxation, not a break. Everything you could send before still works, and more is accepted now.
request.param.optional-added
Additive
No action needed.
request.property.added
Additive
No action needed unless it is required.
request.property.became-nullable
Additive
A relaxation. Existing payloads are unaffected.
response.property.added
Additive
No action needed unless you validate responses against a closed schema.
response.property.type-narrowed
Additive
A tighter guarantee, not a break. Every value you can receive now was already possible, so existing handling still covers it; a null check here may now be dead code.
cosmetic.schema-renamed
Cosmetic
The shape is identical. Only the name changed.
path.param-inlined
Cosmetic
The placeholder accepted a single value, which is now written into the path. Requests go to the same URL; changes inside the endpoint are still reported under its new spelling.
path.params-renamed
Cosmetic
The URL a caller requests is unchanged; only the names in the documented template moved. Changes inside the endpoint are still reported under its new spelling.
request.param.unlisted
Cosmetic
The same parameter still exists as a shared component, or on other operations. This is a documentation drop, not a withdrawn argument.
schema.property-moved-to-composers
Cosmetic
The field left a shared building block and is now declared directly on every schema built from it. Calls that send or read it are unaffected.
schema.property-split-into-variants
Cosmetic
The schema became a set of variants, and every one of them keeps this field. Calls that sent or read it are unaffected.
⇄ marks a rule producer-side tools classify the other way.