response-header-type-compatible

What this check detects

A header value is always text on the wire: `X-Count: 123` sends the characters `1 2 3`, not a binary integer. So changing a header’s declared type between scalars, for example `string` to `integer`, does not change what a client actually receives. A client reading the header as a string still gets a valid string.

This is why oasdiff treats a plain scalar type swap on a header as backward compatible, the same way it treats a scalar query or path parameter. Under a strongly typed body such as JSON the same `string` to `integer` change would be breaking, because there `123` and `"123"` are different values; in a header they are not.

Example

X-Count still carries text like "123" on the wire, so a client reading it as a string is unaffected. The change is reported for awareness, not as breaking.

Mitigation

This change is backward compatible because a header value is transmitted as text, so any type can be represented as a string on the wire and is not enforced there.

Change its severity

oasdiff reports response-header-type-compatible as informational, so it does not fail CI. To treat it as a warning or an error under your own compatibility policy, or to turn it off, set its level in 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-compatible err

Then pass it to oasdiff:

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