breaking_changes.md

Breaking changes

The following table describes potential changes and if they require a version bump.

Keep in mind there may be instances where these rules are violated if there is a pressing performance requirement from the monolith. We will try to keep violations to an absolute minimum, and broadcast the changes in advance if possible.

For the purposes of this document, parameter means input, whereas attribute refers to the response.

Change Description	Version Bump Required
Update description/summary/example	no
Adding attribute	no
Adding optional parameter	no
Adding required parameter	yes
Removing optional attribute	no
Removing required attribute	yes
Removing parameter	no
Optional attribute becomes required	no
Required attribute becomes optional	yes
Optional parameter becomes required	yes
Required parameter becomes optional	no
Changing attribute or parameter name	yes
Changing values in an Enum	yes
Adding values to an attribute Enum	no
Removing values from an attribute Enum	no
Adding values to an parameter Enum	no
Removing values from an parameter Enum	yes
Adding pagination with x-pages	no
Adding attribute minItems	no
Reducing attribute minItems	yes
Increasing attribute minItems	no
Removing attribute minItems=0	no
Removing non-zero attribute minItems	yes
Reducing attribute maxItems	no
Increasing attribute maxItems	yes
Adding parameter minItems=0	no
Adding non-zero parameter minItems	yes
Reducing parameter minItems	no
Increasing parameter minItems	yes
Removing parameter minItems	no
Reducing parameter maxItems	yes
Increasing parameter maxItems	no
Changing cache expiry	no
Changing security requirements	yes
Changing x-required-roles (as dictated)	no

Type changes

For the purposes of this table * means all formats of a type.

Reference document: https://swagger.io/specification/#dataTypes

Original type	New type	Breaking parameter	Breaking attribute
integer/int32	integer/int64	no	yes
integer/int64	integer/int32	yes	no
number/float	number/double	no	no
number/double	number/float	yes	no
number/*	integer/*	yes	no
integer/*	number/*	no	yes
string/date	string/date-time	yes	no
string/date-time	string/date	yes	no

For any parameter or attribute defined with only a type (format is optional according to swagger spec), it is not a breaking change to clarify the definition to add any format within the type.

Any transition not specifically listed is a breaking change for both parameters and attributes.

Enum

As extending enums with new values does not constitute a breaking change treat all string attributes accompanied with enumerations simply as string.