Change catalog

Every change apidiff can report has a stable id, a severity and a changelog category. Run apidiff catalog to list them, or apidiff catalog -f json for tooling.

Severities

severity meaning exit with --fail-on
breaking Existing, correct clients or servers will fail breaking
potentially-breaking Fails only for consumers that make extra assumptions (exhaustive switches, strict parsing, pinned base URLs) potentially-breaking
safe Backwards compatible and functional (new optional field, tightened response) never
info Informational (new operation, deprecation, path parameter rename) never

Direction rules

Schemas are compared in a direction. Data in a request flows client to server, so the new schema must still accept everything the old one accepted: restrictions are breaking, relaxations are safe. Data in a response flows server to client, so the new schema must not produce anything the old one could not: relaxations are at best potentially breaking, restrictions are safe.

change request response
required property added breaking safe
property removed potentially-breaking breaking
property becomes required breaking safe
property becomes optional safe breaking
enum value added safe potentially-breaking
enum value removed breaking safe
maxLength decreased (any upper bound) breaking safe
maxLength increased safe potentially-breaking
became nullable safe breaking
oneOf/anyOf member added safe potentially-breaking
oneOf/anyOf member removed breaking safe

Constraint ids are generated from one table: {request|response}-{keyword}-{tightened|loosened|added|removed} for max-length, min-length, maximum, minimum, exclusive-maximum, exclusive-minimum, max-items, min-items, max-properties, min-properties, pattern (added/removed/changed), multiple-of and unique-items (added/removed).

All 210 change kinds

breaking (68)

id changelog why
discriminator-property-changed changed The field that selects the subtype is different.
operation-removed removed Clients calling the endpoint will fail.
operation-security-added changed Unauthenticated clients are rejected.
operation-security-requirement-removed removed Clients using that credential type are rejected.
operation-security-scopes-added changed Existing tokens lack the new scopes.
parameter-added-required changed Existing clients do not send it, so their requests are rejected.
parameter-became-required changed Clients that omitted it are now rejected.
parameter-explode-changed changed Serialisation of array/object values changed.
parameter-location-changed changed The value is now expected in a different place (query/header/cookie/path).
parameter-style-changed changed Serialisation of the value changed; old requests are parsed differently.
request-additional-properties-restricted changed Extra fields clients send are now rejected.
request-anyof-member-removed removed Clients sending that shape are rejected.
request-became-non-nullable changed Clients sending null are rejected.
request-body-added-required changed Existing clients send no body.
request-body-became-required changed Clients that omitted the body are rejected.
request-discriminator-mapping-changed changed A tag now selects a different schema.
request-discriminator-mapping-removed removed Clients sending that tag are rejected.
request-enum-added changed Previously valid values may be rejected.
request-enum-value-removed removed Clients sending it are rejected.
request-exclusive-maximum-added changed For request data a new restriction appeared: clients may now be rejected.
request-exclusive-maximum-tightened changed For request data allowed values were narrowed: clients may now be rejected.
request-exclusive-minimum-added changed For request data a new restriction appeared: clients may now be rejected.
request-exclusive-minimum-tightened changed For request data allowed values were narrowed: clients may now be rejected.
request-format-added changed Values must now satisfy the format.
request-format-changed changed Values valid under the old format may be invalid.
request-max-items-added changed For request data a new restriction appeared: clients may now be rejected.
request-max-items-tightened changed For request data allowed values were narrowed: clients may now be rejected.
request-max-length-added changed For request data a new restriction appeared: clients may now be rejected.
request-max-length-tightened changed For request data allowed values were narrowed: clients may now be rejected.
request-max-properties-added changed For request data a new restriction appeared: clients may now be rejected.
request-max-properties-tightened changed For request data allowed values were narrowed: clients may now be rejected.
request-maximum-added changed For request data a new restriction appeared: clients may now be rejected.
request-maximum-tightened changed For request data allowed values were narrowed: clients may now be rejected.
request-media-type-removed removed Clients sending that content type get 415.
request-min-items-added changed For request data a new restriction appeared: clients may now be rejected.
request-min-items-tightened changed For request data allowed values were narrowed: clients may now be rejected.
request-min-length-added changed For request data a new restriction appeared: clients may now be rejected.
request-min-length-tightened changed For request data allowed values were narrowed: clients may now be rejected.
request-min-properties-added changed For request data a new restriction appeared: clients may now be rejected.
request-min-properties-tightened changed For request data allowed values were narrowed: clients may now be rejected.
request-minimum-added changed For request data a new restriction appeared: clients may now be rejected.
request-minimum-tightened changed For request data allowed values were narrowed: clients may now be rejected.
request-multiple-of-added changed For request data a new restriction appeared: clients may now be rejected.
request-multiple-of-changed changed For request data the restriction was replaced by an incomparable one: clients may now be rejected.
request-multiple-of-tightened changed For request data allowed values were narrowed: clients may now be rejected.
request-oneof-member-removed removed Clients sending that shape are rejected.
request-pattern-added changed For request data a new restriction appeared: clients may now be rejected.
request-pattern-changed changed For request data the restriction was replaced by an incomparable one: clients may now be rejected.
request-property-added-required changed Existing clients do not send it.
request-property-became-required changed Clients that omitted it are rejected.
request-type-changed changed The wire type is incompatible with the old one.
request-type-narrowed changed Fewer types are accepted, old payloads fail.
request-unique-items-added changed For request data a new restriction appeared: clients may now be rejected.
response-became-nullable changed Clients that never expected null can crash.
response-header-became-optional changed Clients relying on it always being present can fail.
response-header-removed removed Clients reading it get nothing.
response-media-type-removed removed Clients accepting only that type can no longer be served.
response-property-became-optional changed Clients relying on it always being present can fail.
response-property-removed removed Clients reading it get nothing.
response-success-status-removed removed Clients expecting that status never receive it.
response-type-changed changed The wire type is incompatible with the old one.
response-type-widened changed Clients may now receive types they cannot parse.
security-flow-removed removed Clients using that grant are rejected.
security-flow-url-changed changed Token/authorization endpoints moved.
security-scheme-apikey-location-changed changed Clients send the key in the wrong place.
security-scheme-http-scheme-changed changed e.g. basic -> bearer.
security-scheme-removed removed Clients authenticating with it are rejected.
security-scheme-type-changed changed Clients must authenticate differently.

potentially-breaking (46)

id changelog why
default-changed changed Clients omitting the value get different behaviour.
default-removed changed Clients omitting the value may get different behaviour.
discriminator-added changed Generated clients change how they pick a subtype.
discriminator-removed changed Generated clients lose subtype selection.
operation-id-changed changed Code generators derive method names from operationId; SDK users may need to rename calls.
parameter-removed removed Clients that still send it may be rejected or silently lose behaviour.
request-body-removed removed Clients still sending a body may be rejected.
request-property-removed removed Clients still sending it may be rejected (strict servers) or lose behaviour.
response-additional-properties-relaxed changed Clients with strict parsing may reject extra fields.
response-anyof-member-added added Clients may receive a shape they cannot parse.
response-discriminator-mapping-added added Clients may receive an unknown tag.
response-discriminator-mapping-changed changed A tag now selects a different schema.
response-enum-removed changed Clients may see values they never handled.
response-enum-value-added added Clients with exhaustive switches may fail on the new value.
response-exclusive-maximum-loosened changed For response data allowed values were widened: clients may see values outside their assumptions.
response-exclusive-maximum-removed changed For response data a restriction disappeared: clients may see values outside their assumptions.
response-exclusive-minimum-loosened changed For response data allowed values were widened: clients may see values outside their assumptions.
response-exclusive-minimum-removed changed For response data a restriction disappeared: clients may see values outside their assumptions.
response-format-changed changed Clients parsing by format (int32 -> int64, date -> date-time) may break.
response-format-removed changed Clients parsing by format may see unexpected values.
response-max-items-loosened changed For response data allowed values were widened: clients may see values outside their assumptions.
response-max-items-removed changed For response data a restriction disappeared: clients may see values outside their assumptions.
response-max-length-loosened changed For response data allowed values were widened: clients may see values outside their assumptions.
response-max-length-removed changed For response data a restriction disappeared: clients may see values outside their assumptions.
response-max-properties-loosened changed For response data allowed values were widened: clients may see values outside their assumptions.
response-max-properties-removed changed For response data a restriction disappeared: clients may see values outside their assumptions.
response-maximum-loosened changed For response data allowed values were widened: clients may see values outside their assumptions.
response-maximum-removed changed For response data a restriction disappeared: clients may see values outside their assumptions.
response-min-items-loosened changed For response data allowed values were widened: clients may see values outside their assumptions.
response-min-items-removed changed For response data a restriction disappeared: clients may see values outside their assumptions.
response-min-length-loosened changed For response data allowed values were widened: clients may see values outside their assumptions.
response-min-length-removed changed For response data a restriction disappeared: clients may see values outside their assumptions.
response-min-properties-loosened changed For response data allowed values were widened: clients may see values outside their assumptions.
response-min-properties-removed changed For response data a restriction disappeared: clients may see values outside their assumptions.
response-minimum-loosened changed For response data allowed values were widened: clients may see values outside their assumptions.
response-minimum-removed changed For response data a restriction disappeared: clients may see values outside their assumptions.
response-multiple-of-changed changed For response data the restriction was replaced by an incomparable one: clients may see values outside their assumptions.
response-multiple-of-loosened changed For response data allowed values were widened: clients may see values outside their assumptions.
response-multiple-of-removed changed For response data a restriction disappeared: clients may see values outside their assumptions.
response-oneof-member-added added Clients may receive a shape they cannot parse.
response-pattern-changed changed For response data the restriction was replaced by an incomparable one: clients may see values outside their assumptions.
response-pattern-removed changed For response data a restriction disappeared: clients may see values outside their assumptions.
response-unique-items-removed changed For response data a restriction disappeared: clients may see values outside their assumptions.
schema-not-changed changed The set of excluded values changed.
security-scope-removed removed Clients requesting it may be refused.
server-removed removed Clients pinned to that base URL may stop working.

safe (84)

id changelog why
operation-security-removed changed Authenticated clients keep working.
operation-security-requirement-added added Existing credentials keep working.
operation-security-scopes-removed changed Existing tokens remain sufficient.
parameter-added-optional added Clients may ignore it.
parameter-became-optional changed Clients that send it keep working.
request-additional-properties-relaxed changed More inputs accepted.
request-anyof-member-added added Clients may keep sending the old shapes.
request-became-nullable changed More inputs accepted.
request-body-added-optional added Clients may ignore it.
request-body-became-optional changed Clients that send it keep working.
request-discriminator-mapping-added added More inputs accepted.
request-enum-removed changed More inputs accepted.
request-enum-value-added added More inputs accepted.
request-exclusive-maximum-loosened changed For request data allowed values were widened: old requests stay valid.
request-exclusive-maximum-removed changed For request data a restriction disappeared: old requests stay valid.
request-exclusive-minimum-loosened changed For request data allowed values were widened: old requests stay valid.
request-exclusive-minimum-removed changed For request data a restriction disappeared: old requests stay valid.
request-format-removed changed More inputs accepted.
request-max-items-loosened changed For request data allowed values were widened: old requests stay valid.
request-max-items-removed changed For request data a restriction disappeared: old requests stay valid.
request-max-length-loosened changed For request data allowed values were widened: old requests stay valid.
request-max-length-removed changed For request data a restriction disappeared: old requests stay valid.
request-max-properties-loosened changed For request data allowed values were widened: old requests stay valid.
request-max-properties-removed changed For request data a restriction disappeared: old requests stay valid.
request-maximum-loosened changed For request data allowed values were widened: old requests stay valid.
request-maximum-removed changed For request data a restriction disappeared: old requests stay valid.
request-media-type-added added Clients may keep their content type.
request-min-items-loosened changed For request data allowed values were widened: old requests stay valid.
request-min-items-removed changed For request data a restriction disappeared: old requests stay valid.
request-min-length-loosened changed For request data allowed values were widened: old requests stay valid.
request-min-length-removed changed For request data a restriction disappeared: old requests stay valid.
request-min-properties-loosened changed For request data allowed values were widened: old requests stay valid.
request-min-properties-removed changed For request data a restriction disappeared: old requests stay valid.
request-minimum-loosened changed For request data allowed values were widened: old requests stay valid.
request-minimum-removed changed For request data a restriction disappeared: old requests stay valid.
request-multiple-of-loosened changed For request data allowed values were widened: old requests stay valid.
request-multiple-of-removed changed For request data a restriction disappeared: old requests stay valid.
request-oneof-member-added added Clients may keep sending the old shapes.
request-pattern-removed changed For request data a restriction disappeared: old requests stay valid.
request-property-added-optional added Clients may omit it.
request-property-became-optional changed Clients that send it keep working.
request-type-widened changed More types are accepted.
request-unique-items-removed changed For request data a restriction disappeared: old requests stay valid.
response-additional-properties-restricted changed Fewer unexpected fields are produced.
response-anyof-member-removed removed Clients simply stop seeing that shape.
response-became-non-nullable changed Null is no longer produced.
response-discriminator-mapping-removed removed Clients stop seeing that tag.
response-enum-added changed Output is more constrained.
response-enum-value-removed removed Clients simply stop seeing it.
response-error-status-added added Well-behaved clients handle unknown errors generically.
response-error-status-removed removed Clients simply stop seeing that error.
response-exclusive-maximum-added changed For response data a new restriction appeared: clients see a subset of old values.
response-exclusive-maximum-tightened changed For response data allowed values were narrowed: clients see a subset of old values.
response-exclusive-minimum-added changed For response data a new restriction appeared: clients see a subset of old values.
response-exclusive-minimum-tightened changed For response data allowed values were narrowed: clients see a subset of old values.
response-format-added changed Output is more constrained.
response-header-added added Clients may ignore extra headers.
response-header-became-required changed It is now always present.
response-max-items-added changed For response data a new restriction appeared: clients see a subset of old values.
response-max-items-tightened changed For response data allowed values were narrowed: clients see a subset of old values.
response-max-length-added changed For response data a new restriction appeared: clients see a subset of old values.
response-max-length-tightened changed For response data allowed values were narrowed: clients see a subset of old values.
response-max-properties-added changed For response data a new restriction appeared: clients see a subset of old values.
response-max-properties-tightened changed For response data allowed values were narrowed: clients see a subset of old values.
response-maximum-added changed For response data a new restriction appeared: clients see a subset of old values.
response-maximum-tightened changed For response data allowed values were narrowed: clients see a subset of old values.
response-media-type-added added Content negotiation keeps old clients on the old type.
response-min-items-added changed For response data a new restriction appeared: clients see a subset of old values.
response-min-items-tightened changed For response data allowed values were narrowed: clients see a subset of old values.
response-min-length-added changed For response data a new restriction appeared: clients see a subset of old values.
response-min-length-tightened changed For response data allowed values were narrowed: clients see a subset of old values.
response-min-properties-added changed For response data a new restriction appeared: clients see a subset of old values.
response-min-properties-tightened changed For response data allowed values were narrowed: clients see a subset of old values.
response-minimum-added changed For response data a new restriction appeared: clients see a subset of old values.
response-minimum-tightened changed For response data allowed values were narrowed: clients see a subset of old values.
response-multiple-of-added changed For response data a new restriction appeared: clients see a subset of old values.
response-multiple-of-tightened changed For response data allowed values were narrowed: clients see a subset of old values.
response-oneof-member-removed removed Clients simply stop seeing that shape.
response-pattern-added changed For response data a new restriction appeared: clients see a subset of old values.
response-property-added added Tolerant readers ignore new fields.
response-property-became-required changed It is now always present.
response-success-status-added added Clients already handle the existing success path.
response-type-narrowed changed Fewer types are produced.
response-unique-items-added changed For response data a new restriction appeared: clients see a subset of old values.

info (12)

id changelog why
default-added changed Documents existing server behaviour.
operation-added added New endpoints cannot affect existing clients.
operation-deprecated deprecated Signals planned removal; still works today.
operation-undeprecated changed Deprecation was withdrawn.
parameter-deprecated deprecated Signals planned removal.
path-param-renamed changed Templates differing only in parameter names match the same URLs, so wire behaviour is unchanged (generated client signatures may change).
response-description-removed changed Documentation only.
schema-deprecated deprecated Signals planned removal.
security-flow-added added An additional grant is available.
security-scheme-added added A new way to authenticate exists.
security-scope-added added A new scope is available.
server-added added An additional base URL is available.