response-property-enum-value-added

What this check detects

An enum on a response property is a promise to the client about the complete set of values that field can hold. Clients commonly switch on those values and may not have a branch for anything else.

Adding a value means the response can now return something the client was never told about. Whether that breaks a given client depends on how it handles unknown values, so oasdiff reports it as a warning rather than a hard breaking change: worth a review, not an automatic CI failure.

Example

schema:
  type: object
  properties:
    status:
      type: string
      enum: [active, inactive]

schema:
  type: object
  properties:
    status:
      type: string
      enum: [active, inactive, archived]

The "status" response property may now return "archived", which existing clients might not handle.

Mitigation

Adding new enum values to a response can be unexpected for clients; use x-extensible-enum instead.

Change its severity or ignore it

To change the severity oasdiff assigns to response-property-enum-value-added, list its id and a level in a severity-levels file, one rule per line. The level can be err, warn, or info, or none to disable the check entirely:

# severity.txt
response-property-enum-value-added err

Then pass it to oasdiff:

oasdiff changelog base.yaml revision.yaml --severity-levels severity.txt

Setting the level to none disables the check, so it is no longer reported at all.