--- title: "OpenAPI Overlays for Filtering One Spec Into Public, Partner, and Internal Audiences" url: https://daily.dev/posts/openapi-overlays-for-filtering-one-spec-into-public-partner-and-internal-audiences-f5svczuz9 source_url: https://apievangelist.com/2026/07/06/openapi-overlays-for-filtering-multiple-audiences type: article source: "API Evangelist" published: 2026-07-06T14:56:23.475Z updated: 2026-07-06T14:56:44.700Z tags: ["architecture", "backend", "openapi"] reading_time: 4 upvotes: 0 comments: 0 language: 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 Filtering One Spec Into Public, Partner, and Internal Audiences **[API Evangelist](https://daily.dev/sources/apievangelist)** · 4 min read · 0 upvotes · 0 comments ## Summary Teams managing APIs for multiple audiences often end up with diverging hand-edited spec copies. OpenAPI Overlays solve this by keeping one parent OpenAPI definition as the source of truth and applying separate overlay documents to filter out operations per audience. A public overlay removes delete, put, and cancel operations. A partner overlay keeps write access but strips experimental paths and internal response examples. The post also warns about a key gotcha: the `remove` action deletes only the targeted node and does not chase `$ref` references, so removing shared components that other operations still reference will produce dangling refs that fail validation. The recommended approach is to treat the full internal spec as the single source of truth and generate all audience-specific views via small, reviewable overlay files. ## Full article daily.dev links to this article rather than hosting it. Read it at the original source: ## Similar posts on daily.dev - [OpenAPI Overlays for Splitting Public and Internal Documentation](https://daily.dev/posts/openapi-overlays-for-splitting-public-and-internal-documentation-nv1nvt7xd) · 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 Stripping Internal Endpoints Before You Publish](https://daily.dev/posts/openapi-overlays-for-stripping-internal-endpoints-before-you-publish-2ub7euum8) · API Evangelist · 1 upvotes · 0 comments - [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 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 --- Tags: [#architecture](https://daily.dev/tags/architecture), [#backend](https://daily.dev/tags/backend), [#openapi](https://daily.dev/tags/openapi) [View this post on daily.dev](https://daily.dev/posts/openapi-overlays-for-filtering-one-spec-into-public-partner-and-internal-audiences-f5svczuz9)