new-required-request-default-parameter-to-existing-path

What this check detects

A parameter can be declared at the path level (directly under the path, above the individual operations) or at the operation level. A path-level parameter applies to every operation on that path, so a single one added there affects GET, POST, and every other method at once.

This check flags the specific case of a new required parameter added at the path level of an existing path. Because it is inherited by all of the path’s operations, existing clients calling any method on that path now fail unless they send it.

Example

The required "version" parameter is declared once at the path level, so it now applies to GET /users (and any other operation added to this path). Existing clients do not send it, so their requests start failing validation.

How to handle this change

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

Then pass it to oasdiff:

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