new-required-request-property-with-default

What this check detects

It is tempting to assume that giving a new required property a default makes it safe to add, since the server could fill in the default when a client omits it. For a request body, that is not how validation works.

In JSON Schema, and therefore in OpenAPI, required is checked independently of default. A property listed under required must be present in the payload; default is an annotation that documents a fallback value and drives code generation, it does not make a missing required property valid. A server that validates the request rejects a payload that omits the property before any default would apply.

So adding a required property to a request is breaking even when it carries a default: existing clients that do not send it break. The optional-with-default variant, by contrast, is safe, and oasdiff reports it as informational.

Example

schema:
  type: object
  properties:
    name:
      type: string
  required:
    - name

schema:
  type: object
  properties:
    name:
      type: string
    region:
      type: string
      default: us-east-1
  required:
    - name
    - region

The new "region" property is required even though it has a default. Request validation rejects payloads that omit it before the default applies, so existing clients break.

Change its severity or ignore it

To change the severity oasdiff assigns to new-required-request-property-with-default, list its id and a level in a severity-levels file, 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 err

Then pass it to oasdiff:

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

Setting the level to none disables the check, so it is no longer reported at all.