How can I use OpenAPI overlays to add deprecation notices and sunset dates?

How can I use OpenAPI overlays to add deprecation notices and sunset dates? #

Marking an operation deprecated: true tells tooling that something is going away, but it doesn’t tell a developer when, why, or what to use instead. Following the emerging IETF Sunset header convention (RFC 8594) alongside clear documentation is far more actionable, and this kind of time-sensitive documentation change is a great candidate for the OpenAPI Overlay Specification, since the notice period is usually planned well ahead of the actual removal.

Structuring a Complete Deprecation Notice #

overlay: 1.0.0
info:
  title: Orders v1 Sunset Overlay
  version: 1.0.0
actions:
  - target: $.paths['/v1/orders'].get
    update:
      deprecated: true
      description: >
        **Deprecated.** This endpoint will be removed on 2026-12-01.
        Migrate to `GET /v2/orders`, which adds cursor-based pagination
        and consistent field naming. See the migration guide linked below.        
      x-sunset-date: "2026-12-01"
      x-migration-guide: "https://developer.example.com/changelog/orders-v2-migration"

Documenting the Sunset Header in Responses #

If your API actually returns a Sunset header on deprecated endpoints, document it so client developers know to check for it programmatically:

  - target: $.paths['/v1/orders'].get.responses['200'].headers
    update:
      Sunset:
        description: "Date after which this endpoint will stop functioning, per RFC 8594."
        schema:
          type: string
          format: date
        example: "2026-12-01"

Staging Deprecation Notices Ahead of the Actual Date #

A practical workflow is to author the full deprecation overlay as soon as the decision is finalized — often months in advance — and schedule its application to the published documentation at a specific point in the release calendar, rather than waiting until the exact day the endpoint is removed:

# Applied starting the first day of the announced notice period
redocly join openapi.yaml --overlay deprecations/orders-v1-sunset.yaml -o dist/openapi.yaml

Escalating the Notice as the Date Approaches #

Some teams maintain two versions of the same deprecation overlay: an initial “soft” notice, and a more urgent version applied in the final 30 days before removal:

  - target: $.paths['/v1/orders'].get
    update:
      description: >
        **⚠ This endpoint will be removed in less than 30 days (2026-12-01).**
        Please migrate to `GET /v2/orders` immediately.

Automatically Removing the Notice After Sunset #

Once the actual removal date passes and the operation is deleted from the base document entirely, the corresponding overlay action becomes a no-op (since its target no longer exists). At that point, delete the stale overlay file as part of the same change that removes the operation, to keep the deprecations/ folder representing only currently active notices.

See What is the OpenAPI Overlay Specification? and How can I use OpenAPI overlays to mark operations as deprecated? for the more basic version of this technique.

Last updated on July 16, 2026.