Driftwatch

How this is decided

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.

  1. A response property becoming optional is safe for a producer and a null dereference waiting to happen for you.
  2. A new enum value in a response is additive for a producer. It breaks exhaustive switches, strict parsers and generated client enums.
  3. 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

RuleSeverityWhat it does to calling code
operation.removedBreakingThis verb now 405s. The path still resolves, so a health check on the URL will not catch it.
path.movedBreakingThe 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.removedBreakingRequests to this path now 404.
request.enum.value-removedBreakingA value you may have hardcoded is now rejected.
request.param.became-requiredBreakingCalls that omit it are rejected.
request.param.removed ⇄BreakingNo error is raised. The value is ignored and your results change silently, which is the hardest class of break to notice.
request.param.required-addedBreakingEvery existing call that omits it is rejected.
request.property.became-requiredBreakingPartial payloads are rejected.
request.property.removed ⇄BreakingUsually ignored rather than rejected, so the call succeeds and does something subtly different.
request.property.type-changedBreakingSerialization mismatch. Integer-to-string moves are the usual cause and the usual outage.
response.enum.constraint-removed ⇄BreakingThe 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 ⇄BreakingProducer-side tools call this additive. It breaks exhaustive switches, strict parsers and generated client enums.
response.property.became-optional ⇄BreakingProducer-side tools call this non-breaking. For a consumer it is a null dereference on an unknown future date.
response.property.removedBreakingReads of this field return undefined, and the failure surfaces wherever that value is used rather than at the call.
response.property.type-changedBreakingParse failure, or silent coercion depending on your client.
security.alternative-removedBreakingCallers using the withdrawn credentials are rejected. Callers already on a remaining option are unaffected.
security.scheme-changedBreakingThe integration needs reworking, not patching.
security.scope-addedBreakingExisting tokens 403. This needs user re-consent, not a code change, so it cannot be fixed by deploying.
operation.deprecatedDeprecationStill works today. This is the earliest warning you will get before it is removed.
default.value-changedBehavioralBehavior shifts for every call that omits the field.
pagination.default-changedBehavioralSilent truncation. Code that does not paginate keeps working and quietly returns a different slice of the data.
response.property.now-always-nullBehavioralNothing 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-nullableBehavioralThe 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.addedBehavioralAn unhandled branch in your error handling.
response.status-code.removedBehavioralDead branch, or an undocumented response you still receive.
schema.composition-changedBehavioralThe set of shapes this value can take changed. Worth a look, but the structural diff cannot say precisely how.
schema.property-narrowed-to-variantsBehavioralThe 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-retargetedBehavioralOften 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-removedBehavioralThe operation no longer demands this credential.
operation.addedAdditiveNo action needed.
operation.undeprecatedAdditiveThe operation is supported again.
path.addedAdditiveNo action needed.
request.enum.constraint-removedAdditiveA relaxation, not a break. Everything you could send before still works, and more is accepted now.
request.param.optional-addedAdditiveNo action needed.
request.property.addedAdditiveNo action needed unless it is required.
request.property.became-nullableAdditiveA relaxation. Existing payloads are unaffected.
response.property.addedAdditiveNo action needed unless you validate responses against a closed schema.
response.property.type-narrowedAdditiveA 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-renamedCosmeticThe shape is identical. Only the name changed.
path.param-inlinedCosmeticThe 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-renamedCosmeticThe 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.unlistedCosmeticThe 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-composersCosmeticThe 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-variantsCosmeticThe 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.