api-path-removed-before-sunset

What this check detects

OpenAPI lets you retire an endpoint gracefully instead of deleting it outright. You first mark the operation deprecated: true, which is not itself a breaking change: it only signals an intent to remove. oasdiff also reads an x-sunset extension, an RFC 3339 date that announces when the endpoint will actually be removed, so clients know how long they have to migrate.

This check fires when a path and its operations are deleted before that announced sunset date has passed, that is, earlier than clients were told to expect. Removing the path on or after its sunset date is allowed and is not reported; removing it early breaks clients that were still relying on the promised window.

Example

paths:
  /v1/users:
    get:
      deprecated: true
      x-sunset: '2027-01-01'
      responses:
        '200':
          description: OK
  /v1/health:
    get:
      responses:
        '200':
          description: OK

paths:
  /v1/health:
    get:
      responses:
        '200':
          description: OK

/v1/users was removed while its announced sunset date (2027-01-01) was still in the future. Removing it on or after the sunset date would not be reported.

Change its severity or ignore it

To change the severity oasdiff assigns to api-path-removed-before-sunset, 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
api-path-removed-before-sunset warn

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.