response-header-type-changed

What this check detects

A response header is transmitted as text, but its declared type and format tell clients how to parse the value. This check fires when that type or format changes so that a client written against the old contract can no longer parse the header.

The canonical case is dropping a format the client parses. A `Retry-After` header declared as `string` with `format: date-time` that becomes `integer` breaks a client that parses it as an HTTP date, because it now receives a bare number like `120`. Because a header value is text on the wire, a plain type swap with no format (for example `string` to `integer`) is not breaking on its own (that is reported as backward compatible); it is a dropped or incompatible format, or an otherwise incompatible type change, that breaks clients here.

Example

A client that parses Retry-After as an HTTP date (string/date-time) fails when the server starts returning a bare integer like "120".

How to handle this change

When oasdiff flags response-header-type-changed, 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-header-type-changed 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-header-type-changed warn

Then pass it to oasdiff:

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