How can I use OpenAPI overlays to mark operations as deprecated?

How can I use OpenAPI overlays to mark operations as deprecated? #

Deprecating an operation is rarely a single edit — it typically involves setting the deprecated flag, updating the description with a migration path, and sometimes adding a Sunset header or custom extension noting the removal date. Doing this consistently across a large spec, especially when deprecation timing is planned ahead of the actual code change, is a great fit for the OpenAPI Overlay Specification.

The Standard `deprecated` Field #

OpenAPI already defines a boolean deprecated field on operations and schemas. An overlay can set it without modifying the underlying implementation-facing document:

overlay: 1.0.0
info:
  title: Q3 2026 Deprecation Overlay
  version: 1.0.0
actions:
  - target: $.paths['/v1/orders'].get
    update:
      deprecated: true
      description: "Deprecated: use GET /v2/orders instead. This endpoint will be removed on 2026-12-01."

Deprecating an Entire Schema #

Whole schemas can be marked deprecated the same way, which is useful when an older representation is being phased out in favor of a new one:

  - target: $.components.schemas.LegacyOrder
    update:
      deprecated: true
      description: "Deprecated in favor of the Order schema. Will be removed in a future major version."

Adding a Machine-Readable Sunset Date #

Since OpenAPI’s built-in deprecated field is just a boolean, teams often add a vendor extension carrying the actual removal date so tooling (and generated client warnings) can react to it programmatically:

  - target: $.paths['/v1/orders'].get
    update:
      x-sunset: "2026-12-01"
      x-deprecation-link: "https://developer.example.com/changelog/orders-v2-migration"

Deprecating Multiple Operations at Once #

If an entire API version is being sunset, JSONPath wildcards let you apply the same deprecation metadata to every operation under a path prefix in one action, provided your tooling resolves the wildcard against your document structure:

  - target: $.paths['/v1/orders'].*
    update:
      deprecated: true
      x-sunset: "2026-12-01"

Always verify the merged output; some overlay processors require one action per HTTP method rather than a wildcard across methods, depending on implementation maturity.

Staging Deprecation Ahead of Time #

A powerful pattern is to write the deprecation overlay as soon as the decision is made, well before the actual removal date, and only merge it into the “current” published documentation once a feature flag or release date is reached. This lets the documentation and API changelog stay perfectly synchronized with the actual sunset timeline.

Applying the Overlay in CI #

redocly join openapi.yaml --overlay deprecations/2026-q3.yaml -o dist/openapi.yaml

Because deprecation overlays are dated and scoped to a specific release, keeping them in a deprecations/ folder named by quarter or release version gives you a clear historical audit trail of what was deprecated and when.

See What is the OpenAPI Overlay Specification? for the general mechanism, and How can I use OpenAPI overlays to add deprecation notices and sunset dates? for a deeper look at communicating sunset timelines to consumers.

Last updated on July 16, 2026.