--- title: OpenAPI Overlays for Deprecation and Migration Choreography description: Deprecating API operations by hand across multiple specs invites drift and irreversible mistakes. OpenAPI Overlays let teams mark operations deprecated with... canonical: https://daily.dev/posts/openapi-overlays-for-deprecation-and-migration-choreography-ik5yw3m0o twitter:card: summary_large_image twitter:site: @dailydotdev og:type: website og:site_name: daily.dev og:title: OpenAPI Overlays for Deprecation and Migration Choreography | daily.dev og:description: Deprecating API operations by hand across multiple specs invites drift and irreversible mistakes. OpenAPI Overlays let teams mark operations deprecated with... og:url: https://daily.dev/posts/openapi-overlays-for-deprecation-and-migration-choreography-ik5yw3m0o og:image: https://api.daily.dev/og/posts/ik5yw3m0O.png og:image:alt: OpenAPI Overlays for Deprecation and Migration Choreography og:image:width: 1200 og:image:height: 630 og:locale: en --- > ## Documentation Index > Fetch the complete documentation index at: https://daily.dev/llms.txt > Use this file to discover all available pages before exploring further. # OpenAPI Overlays for Deprecation and Migration Choreography **[API Evangelist](https://daily.dev/sources/apievangelist)** · 4 min read · 0 upvotes · 0 comments ## Summary Deprecating API operations by hand across multiple specs invites drift and irreversible mistakes. OpenAPI Overlays let teams mark operations deprecated with consistent language, document RFC 8594 Sunset and RFC 9745 Deprecation response headers, and schedule sunset dates without touching the source spec. Overlays use JSONPath targeting to sweep every operation carrying a given tag across one or many specs at once. Because the overlay is a separate, diffable file that extends the base spec, the deprecation can be previewed in a pull request, applied in CI on the sunset date, and simply deleted to roll back cleanly if a migration slips. ## Full article daily.dev links to this article rather than hosting it. Read it at the original source: ## Questions this post answers ### What HTTP headers should I set when deprecating an API operation according to RFC 8594 and RFC 9745? Use the Sunset header from RFC 8594, which carries a full HTTP-date (IMF-fixdate format, e.g. 'Sat, 01 Jan 2027 00:00:00 GMT'), not a bare date like '2027-01-01'. Use the Deprecation header from RFC 9745, which is boolean-ish ('true') rather than a date, with the actual removal timeline expressed via the Sunset header and a Link relation pointing to the replacement. _daily.dev surfaces practical guidance like this for teams shipping API deprecations without breaking consumers._ ### How do I mark multiple OpenAPI operations as deprecated at once without editing the source spec? Use an OpenAPI Overlay with a JSONPath target such as $.paths.*[?(@.tags && 'legacy' in @.tags)] to select every operation carrying a given tag, then apply an update block setting deprecated: true and a shared description across all of them in one pass. The overlay never modifies the source spec, so it can be previewed as a diff, applied in CI on the sunset date, and deleted to revert cleanly if plans change. _Teams standardizing deprecation across many API specs can track patterns like this through daily.dev._ ## Similar posts on daily.dev - [The Many Use Cases for OpenAPI Overlays](https://daily.dev/posts/the-many-use-cases-for-openapi-overlays-1gjpvrair) · API Evangelist · 0 upvotes · 0 comments - [OpenAPI Overlays for Separation of Concerns When You Do Not Own the Spec](https://daily.dev/posts/openapi-overlays-for-separation-of-concerns-when-you-do-not-own-the-spec-zhy9th4pq) · API Evangelist · 0 upvotes · 0 comments - [OpenAPI Overlays for Improving Developer Experience: Enriching a Thin, Code-Generated Spec](https://daily.dev/posts/openapi-overlays-for-improving-developer-experience-enriching-a-thin-code-generated-spec-qiejsxc37) · API Evangelist · 0 upvotes · 0 comments - [OpenAPI Overlays for Adding Tool-Specific Content Without Polluting the Spec](https://daily.dev/posts/openapi-overlays-for-adding-tool-specific-content-without-polluting-the-spec-np7suyu3c) · API Evangelist · 0 upvotes · 0 comments - [API Versioning Should Be Your Last Resort](https://daily.dev/posts/api-versioning-should-be-your-last-resort-vywyleewk) · Milan Jovanović · 47 upvotes · 5 comments --- Tags: [#openapi](https://daily.dev/tags/openapi) [View this post on daily.dev](https://daily.dev/posts/openapi-overlays-for-deprecation-and-migration-choreography-ik5yw3m0o) ```json {"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://daily.dev/#organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180},"sameAs":["https://twitter.com/dailydotdev","https://github.com/dailydotdev","https://www.linkedin.com/company/daily-dev-ltd"]},{"@type":"WebSite","@id":"https://daily.dev/#website","url":"https://daily.dev","name":"daily.dev","publisher":{"@id":"https://daily.dev/#organization"},"potentialAction":{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https://daily.dev/search?q={search_term_string}"},"query-input":"required name=search_term_string"}}]} {"@context":"https://schema.org","@type":"TechArticle","headline":"OpenAPI Overlays for Deprecation and Migration Choreography","url":"https://daily.dev/posts/openapi-overlays-for-deprecation-and-migration-choreography-ik5yw3m0o","mainEntityOfPage":{"@type":"WebPage","@id":"https://daily.dev/posts/openapi-overlays-for-deprecation-and-migration-choreography-ik5yw3m0o"},"datePublished":"2026-08-14T10:26:29.502Z","dateModified":"2026-09-13T19:57:13.642Z","description":"Deprecating API operations by hand across multiple specs invites drift and irreversible mistakes. OpenAPI Overlays let teams mark operations deprecated with...","image":"https://media.daily.dev/image/upload/f_auto,q_auto/v1/posts/a859410f8637ab0a6b43430b42020db1?_a=AQAEuop","thumbnailUrl":"https://media.daily.dev/image/upload/f_auto,q_auto/v1/posts/a859410f8637ab0a6b43430b42020db1?_a=AQAEuop","isAccessibleForFree":true,"articleSection":"API Evangelist","inLanguage":"en","publisher":{"@type":"Organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180}},"author":{"@type":"Organization","name":"API Evangelist","logo":"https://media.daily.dev/image/upload/t_logo,f_auto/v1/logos/a36244ae67bc4f41a605f780267ecb5f","url":"https://daily.dev/sources/apievangelist"},"commentCount":0,"discussionUrl":"https://daily.dev/posts/openapi-overlays-for-deprecation-and-migration-choreography-ik5yw3m0o","interactionStatistic":[{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":0},{"@type":"InteractionCounter","interactionType":{"@type":"CommentAction"},"userInteractionCount":0}],"keywords":"openapi","timeRequired":"PT4M"} {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://daily.dev"},{"@type":"ListItem","position":2,"name":"API Evangelist","item":"https://daily.dev/sources/apievangelist"},{"@type":"ListItem","position":3,"name":"OpenAPI Overlays for Deprecation and Migration Choreography"}]} {"@context":"https://schema.org","@type":"FAQPage","@id":"https://daily.dev/posts/openapi-overlays-for-deprecation-and-migration-choreography-ik5yw3m0o#faq","mainEntity":[{"@type":"Question","name":"What HTTP headers should I set when deprecating an API operation according to RFC 8594 and RFC 9745?","acceptedAnswer":{"@type":"Answer","text":"Use the Sunset header from RFC 8594, which carries a full HTTP-date (IMF-fixdate format, e.g. 'Sat, 01 Jan 2027 00:00:00 GMT'), not a bare date like '2027-01-01'. Use the Deprecation header from RFC 9745, which is boolean-ish ('true') rather than a date, with the actual removal timeline expressed via the Sunset header and a Link relation pointing to the replacement. daily.dev surfaces practical guidance like this for teams shipping API deprecations without breaking consumers."}},{"@type":"Question","name":"How do I mark multiple OpenAPI operations as deprecated at once without editing the source spec?","acceptedAnswer":{"@type":"Answer","text":"Use an OpenAPI Overlay with a JSONPath target such as $.paths.*[?(@.tags && 'legacy' in @.tags)] to select every operation carrying a given tag, then apply an update block setting deprecated: true and a shared description across all of them in one pass. The overlay never modifies the source spec, so it can be previewed as a diff, applied in CI on the sunset date, and deleted to revert cleanly if plans change. Teams standardizing deprecation across many API specs can track patterns like this through daily.dev."}}]} ```