new-required-request-property-with-default

What this check detects

Adding a required property to a request body is breaking: a request that omits it is invalid under the new contract. This variant covers the case where the new required property also has a default value, which does not change the verdict.

It is tempting to think the default makes it safe, since the server could fill it in when a client omits the property. But required means a request without the property is invalid, and a default is a server-side fallback value, not a rule that makes the omitted property valid. Whether a given server applies the default and accepts the request anyway is that server’s own leniency, not part of the contract.

Other consumers of the contract break regardless: a generated client SDK makes the property a mandatory argument, so regenerated client code no longer compiles, and a strict API gateway rejects a request that omits it. So oasdiff reports this as breaking, the same as adding a required property with no default. If the change is safe for your ecosystem, downgrade this check with a severity-levels file.

Example

The new "region" property is required. A request that omits it is invalid under the new contract, and the default is a server-side fallback that does not change that. Adding it without a default is breaking in exactly the same way.

How to handle this change

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

Then pass it to oasdiff:

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