new-required-request-parameter

What this check detects

A new required parameter, in the query, header, path, or cookie, was added to an operation. Existing clients do not send it, so their requests are now invalid under the new contract and fail validation.

To add a parameter without breaking clients, make it optional (with a sensible default behavior when omitted), or version the endpoint.

Example

GET /users now requires a "tenant" query parameter. Existing clients that omit it start failing.

How to handle this change

When oasdiff flags new-required-request-parameter, 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 new-required-request-parameter 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
new-required-request-parameter warn

Then pass it to oasdiff:

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