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

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.

How to handle this change

When oasdiff flags response-property-enum-value-added, you have a few ways to respond:

• Find a backward-compatible alternative. Redesign the change so clients that followed the old contract keep working, and agree on the approach with whoever introduced it.
• Release it in a new API version. Keep the current contract and introduce the change in a new version, then deprecate the old one with a sunset date so clients have time to migrate.
• Accept it as a deliberate breaking change. Sometimes a breaking change is unavoidable, such as an urgent or security fix. Approve it knowingly, document it in your release notes, and tell affected clients. This should be the exception, not a routine way of working.

If oasdiff's verdict does not match your API's compatibility policy, you can also change how it treats response-property-enum-value-added with a severity-levels file:

Put 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