esi-docs

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.