OpenAPI Breaking Changes - A Formal Definition
We recently added a small but important enhancement to oasdiff that prints all supported checks for changes in OpenAPI, the `oasdiff checks` command:
The `checks` command currently lists 250 checks of which 121 are breaking changes with level "error" or "warn". The rest are informational.
Why is this important? Because it provides a first of its kind (as far as I know) formal list of OpenAPI breaking changes, something that was desperately needed but didn't exist previously.
When we first started developing oasdiff, the concept of a breaking change was quite vague. I couldn't find an intensional definition, the conditions for when a change is considered breaking, nor an extensional definition, the exact list of breaking changes. This made our work much more challenging as we needed to compile the list ourselves, using common-sense and feedback from users.
With the help of our community we did it, and now the world has, for the first time, a comprehensive list of all breaking changes in OpenAPI.
We will continue to refine this list until it is perfect, with your help of course :-)
ID DESCRIPTION LEVEL
added-required-request-body required request body added error
api-deprecated-sunset-parse endpoint deprecated with invalid or missing sunset date error
api-global-security-added security scheme added in security info
api-global-security-removed security scheme deleted in security info
api-global-security-scope-added scope added to a security scheme in security info
api-global-security-scope-removed scope deleted from a security scheme in security info
api-operation-id-added operation ID added to an endpoint info
api-operation-id-removed operation ID deleted from an endpoint error
api-path-removed-before-sunset path and endpoint deleted before sunset date error
api-path-removed-without-deprecation path and endpoint deleted without deprecation error
api-path-sunset-parse path and endpoint deleted with invalid or missing sunset date error
api-removed-before-sunset endpoint deleted before sunset date error
api-removed-without-deprecation endpoint deleted without deprecation error
api-schema-removed schema deleted from components/schemas error
api-security-added security requirements added to endpoint info
api-security-component-added security scheme added in components/securitySchemes info
api-security-component-oauth-scope-added scope added to OAuth flow in components/securitySchemes info
api-security-component-oauth-scope-changed scope modified in OAuth flow in components/securitySchemes info
api-security-component-oauth-scope-removed scope deleted from OAuth flow in components/securitySchemes info
api-security-component-oauth-token-url-changed token URL modified in OAuth flow in components/securitySchemes info
api-security-component-oauth-url-changed auth URL modified in OAuth flow in components/securitySchemes info
api-security-component-removed security scheme deleted in components/securitySchemes info
api-security-component-type-changed security scheme type modified in components/securitySchemes info
api-security-removed security requirements deleted from endpoint info
api-security-scope-added scope added to an endpoint's security scheme info
api-security-scope-removed scope deleted from an endpoint's security scheme info
api-stability-decreased endpoint stability level decreased error
api-sunset-date-changed-too-small modified sunset date doesn't meet min required deprecation days error
api-sunset-date-too-small deprecated endpoint sunset before min required deprecation days error
api-tag-added endpoint tag added info
api-tag-removed endpoint tag deleted error
endpoint-added endpoint added info
endpoint-deprecated endpoint deprecated info
endpoint-reactivated endpoint reactivated (deprecation set to false) info
new-optional-request-default-parameter-to-existing-path optional request parameter added at path level info
new-optional-request-parameter optional request parameter added to endpoint info
new-optional-request-property optional property added to request info
new-request-path-parameter new request path parameter error
new-required-request-default-parameter-to-existing-path required request parameter added at path level error
new-required-request-header-property new required request header error
new-required-request-parameter required request parameter added to endpoint error
new-required-request-property required property added to request error
optional-response-header-removed optional response header deleted warning
parsing-error invalid stability level error
request-body-all-of-added sub-schema added to allOf in request body error
request-body-all-of-removed sub-schema deleted from allOf in request body warning
request-body-any-of-added sub-schema added to anyOf in request body info
request-body-any-of-removed sub-schema deleted from anyOf in request body error
request-body-became-enum request body restricted to enum error
request-body-became-not-nullable null excluded as a possible value in request body error
request-body-became-nullable null added as a possible value in request body info
request-body-became-optional request body became optional info
request-body-became-required request body became required error
request-body-default-value-added request body default value set info
request-body-default-value-changed request body default value modified info
request-body-default-value-removed request body default value unset info
request-body-discriminator-added request body discriminator added info
request-body-discriminator-mapping-added request body discriminator mapping added info
request-body-discriminator-mapping-changed request body discriminator mapping changed info
request-body-discriminator-mapping-deleted request body discriminator mapping deleted info
request-body-discriminator-property-name-changed request body discriminator property name changed info
request-body-discriminator-removed request body discriminator deleted info
request-body-enum-value-removed request body enum value deleted error
request-body-max-decreased request body max decreased error
request-body-max-increased request body max increased info
request-body-max-length-decreased request body max length decreased error
request-body-max-length-increased request body max length increased info
request-body-max-length-set request body max length set warning
request-body-max-set request body max set warning
request-body-media-type-added request body media-type added info
request-body-media-type-removed request body media-type deleted error
request-body-min-decreased request body min decreased info
request-body-min-increased request body min increased error
request-body-min-items-increased request-body-min-items-increased-description error
request-body-min-items-set request-body-min-items-set-description warning
request-body-min-length-decreased request body min length decreased info
request-body-min-length-increased request body min length increased error
request-body-min-set request body min set warning
request-body-one-of-added sub-schema added to oneOf in request body info
request-body-one-of-removed sub-schema deleted from oneOf in request body error
request-body-type-changed request body type changed error
request-header-property-became-enum request header property restricted to enum error
request-header-property-became-required request header property became required error
request-optional-property-became-not-read-only request optional property became not read-only info
request-optional-property-became-not-write-only request optional property became not write-only info
request-optional-property-became-read-only request optional property became read-only info
request-optional-property-became-write-only request optional property became write-only info
request-parameter-became-enum request parameter restricted to enum error
request-parameter-became-optional request parameter became optional info
request-parameter-became-required request parameter became required error
request-parameter-default-value-added request parameter default value set error
request-parameter-default-value-changed request parameter default value changed error
request-parameter-default-value-removed request parameter default value unset error
request-parameter-enum-value-added request parameter enum value added info
request-parameter-enum-value-removed request parameter enum value deleted error
request-parameter-max-decreased request parameter max decreased error
request-parameter-max-increased request parameter max increased info
request-parameter-max-items-decreased request parameter max items decreased error
request-parameter-max-items-increased request parameter max items increased info
request-parameter-max-length-decreased request parameter max length decreased error
request-parameter-max-length-increased request parameter max length increased info
request-parameter-max-length-set request parameter max length set warning
request-parameter-max-set request parameter max set warning
request-parameter-min-decreased request parameter min decreased info
request-parameter-min-increased request parameter min increased error
request-parameter-min-items-decreased request parameter min items decreased info
request-parameter-min-items-increased request parameter min items increased error
request-parameter-min-items-set request parameter min items set warning
request-parameter-min-length-decreased request parameter min length decreased info
request-parameter-min-length-increased request parameter min length increased error
request-parameter-min-set request parameter min set warning
request-parameter-pattern-added request parameter pattern set warning
request-parameter-pattern-changed request parameter pattern changed warning
request-parameter-pattern-removed request parameter pattern unset info
request-parameter-removed request parameter deleted warning
request-parameter-type-changed request parameter type changed error
request-parameter-x-extensible-enum-value-removed request parameter-x-extensible-enum value deleted error
request-property-all-of-added sub-schema added to allOf in request property error
request-property-all-of-removed sub-schema deleted from allOf in request property warning
request-property-any-of-added sub-schema deleted from anyOf in request property info
request-property-any-of-removed sub-schema deleted from anyOf in request property error
request-property-became-enum request property restricted to enum error
request-property-became-not-nullable request property became not nullable error
request-property-became-nullable request property became nullable info
request-property-became-optional request property became optional info
request-property-became-required request property became required error
request-property-default-value-added request property default value set info
request-property-default-value-changed request property default-value changed info
request-property-default-value-removed request property default-value unset info
request-property-discriminator-added request property discriminator added info
request-property-discriminator-mapping-added request property discriminator mapping added info
request-property-discriminator-mapping-changed request property discriminator mapping changed info
request-property-discriminator-mapping-deleted request property discriminator mapping deleted info
request-property-discriminator-property-name-changed request property discriminator property name changed info
request-property-discriminator-removed request property discriminator removed info
request-property-enum-value-added request property enum value added info
request-property-enum-value-removed request property enum value removed error
request-property-max-decreased request property max decreased error
request-property-max-increased request property max increased info
request-property-max-length-decreased request property max length decreased error
request-property-max-length-increased request property max length increased info
request-property-max-length-set request property max length set warning
request-property-max-set request property max set warning
request-property-min-decreased request property min decreased info
request-property-min-increased request property min increased error
request-property-min-items-increased request property min items increased error
request-property-min-items-set request property min items set warning
request-property-min-length-decreased request property min length decreased info
request-property-min-length-increased request property min length increased error
request-property-min-set request property min set warning
request-property-one-of-added sub-schema added to oneOf in request property info
request-property-one-of-removed sub-schema deleted from oneOf in request property error
request-property-pattern-added request property pattern set warning
request-property-pattern-changed request property pattern changed warning
request-property-pattern-removed request property pattern unset info
request-property-removed request property removed warning
request-property-type-changed request property type changed info
request-property-x-extensible-enum-value-removed request property x-extensible-enum value removed error
request-required-property-became-not-read-only request required property became not read-only info
request-required-property-became-not-write-only request required property became not write-only info
request-required-property-became-read-only request required property became read-only info
request-required-property-became-write-only request required property became write-only info
required-response-header-removed required response header removed error
response-body-all-of-added sub-schema added to allOf in response body info
response-body-all-of-removed sub-schema removed from allOf in response body info
response-body-any-of-added sub-schema added to anyOf in response body info
response-body-any-of-removed sub-schema removed from anyOf in response body info
response-body-became-nullable response body became nullable error
response-body-default-value-added response body default value set info
response-body-default-value-changed response body default value changed info
response-body-default-value-removed response body default value unset info
response-body-discriminator-added response body discriminator added info
response-body-discriminator-mapping-added response body discriminator mapping added info
response-body-discriminator-mapping-changed response body discriminator mapping changed info
response-body-discriminator-mapping-deleted response body discriminator mapping deleted info
response-body-discriminator-property-name-changed response body discriminator property name changed info
response-body-discriminator-removed response body discriminator removed info
response-body-max-increased response body max increased error
response-body-max-length-increased response body max length increased error
response-body-max-length-unset response body max length unset error
response-body-min-decreased response body min decreased error
response-body-min-items-decreased response body min items decreased error
response-body-min-items-unset response body min items unset error
response-body-min-length-decreased response body min length decreased error
response-body-one-of-added sub-schema added to oneOf in response body info
response-body-one-of-removed sub-schema removed from oneOf in response body info
response-body-type-changed response body type changed error
response-header-became-optional response header became optional error
response-media-type-added response media type added info
response-media-type-removed response media type removed error
response-mediatype-enum-value-removed response mediatype enum value removed error
response-non-success-status-added response non-success status added info
response-non-success-status-removed response non-success status removed error
response-optional-property-added response optional property added info
response-optional-property-became-not-read-only response optional property became not read-only info
response-optional-property-became-not-write-only response optional property became not write-only info
response-optional-property-became-read-only response optional property became read-only info
response-optional-property-became-write-only response optional property became write-only info
response-optional-property-removed response optional property removed warning
response-optional-write-only-property-added response optional write-only property added info
response-optional-write-only-property-removed response optional write-only property removed info
response-property-all-of-added sub-schema added to allOf in response property info
response-property-all-of-removed sub-schema removed from allOf in response property info
response-property-any-of-added sub-schema added to anyOf in response property info
response-property-any-of-removed sub-schema removed from anyOf in response property info
response-property-became-nullable response property became nullable error
response-property-became-optional response property became optional error
response-property-became-required response property became required info
response-property-default-value-added response property default value set info
response-property-default-value-changed response property default value changed info
response-property-default-value-removed response property default value unset info
response-property-discriminator-added response property discriminator added info
response-property-discriminator-mapping-added response property discriminator mapping added info
response-property-discriminator-mapping-changed response property discriminator mapping changed info
response-property-discriminator-mapping-deleted response property discriminator mapping deleted info
response-property-discriminator-property-name-changed response property discriminator property name changed info
response-property-discriminator-removed response property discriminator removed info
response-property-enum-value-added response property enum value added warning
response-property-enum-value-removed response property enum value removed error
response-property-max-increased response property max increased error
response-property-max-length-increased response property max length increased error
response-property-max-length-unset response property max length unset error
response-property-min-decreased response property min decreased error
response-property-min-items-decreased response property min items decreased error
response-property-min-items-unset response property min items unset error
response-property-min-length-decreased response property min length decreased error
response-property-one-of-added sub-schema added to oneOf in response property info
response-property-one-of-removed sub-schema removed from oneOf in response property info
response-property-pattern-added response property pattern set info
response-property-pattern-changed response property pattern changed info
response-property-pattern-removed response property pattern unset info
response-property-type-changed response property type changed error
response-required-property-added response required property added error
response-required-property-became-not-read-only response required property became not read-only info
response-required-property-became-not-write-only response required property became not write-only warning
response-required-property-became-read-only response required property became read-only info
response-required-property-became-write-only response required property became write-only info
response-required-property-removed response required property removed error
response-required-write-only-property-added response required write-only property added info
response-required-write-only-property-removed response required write-only property removed info
response-success-status-added response success status added error
response-success-status-removed response success status removed error
response-write-only-property-became-optional response write-only property became optional error
response-write-only-property-became-required response write-only property became required info
response-write-only-property-enum-value-added response write-only property enum value added info
sunset-deleted sunset deleted error
unparseable-parameter-from-x-extensible-enum unparseable x-extensible-enum in original request parameter error
unparseable-parameter-to-x-extensible-enum unparseable x-extensible-enum in revised request parameter error
unparseable-property-from-x-extensible-enum unparseable x-extensible-enum in original request property error
unparseable-property-to-x-extensible-enum unparseable x-extensible-enum in revised request property error