OpenAPI Overlays is the specification that solves a problem the API world has quietly struggled with for years: how do you modify, extend, or specialize an OpenAPI definition without altering the original, and without loading every possible concern into a single bloated file. Overlays let you apply a layer of targeted changes on top of a base OpenAPI definition — adding examples, translating descriptions, injecting governance metadata, specializing for a particular audience — while leaving the source of truth untouched. This sounds modest, but it addresses something genuinely important about how API definitions work in practice: the base definition shouldn’t have to carry every concern for every consumer, and Overlays give you a clean way to keep the source pristine while applying the specialized modifications different consumers and contexts need. It’s one of the more practically useful specifications to come out of the OpenAPI Initiative, and it fits a gap I’d felt for a long time.
The core problem Overlays solves is API definition bloat, and I named it directly. I wrote in 2024 that we are loading too much into our OpenAPIs — the recognition that as organizations try to make their OpenAPI definitions serve every purpose (documentation, governance, SDK generation, vendor extensions, localization, examples), the definitions become overloaded, unwieldy, and hard to maintain. Overlays are the solution to this bloat: instead of cramming everything into the base definition, you keep the base clean and apply Overlays for the specialized concerns. A documentation team can apply an Overlay with rich examples; a localization team can apply an Overlay with translated descriptions; a governance team can apply an Overlay with compliance metadata — all without touching or fighting over the single base definition. Overlays let different stakeholders work on their concerns independently, layered on top of a shared source of truth, which is exactly what large organizations need.
The source-of-truth-and-derivatives framing is where Overlays fit into my deeper thinking about API definitions, and it’s the conceptual home for them. I wrote in 2024 about the API source of truth as well as the echoes and overlays of that truth — and Overlays are literally the “overlays” in that framing. There’s the base truth, the canonical OpenAPI definition; there are echoes, the various derivatives like documentation and SDKs; and there are overlays, the targeted layers of modification applied on top. Overlays preserve the integrity of the source of truth by keeping modifications in a separate, declarative layer rather than mutating the base. This matters enormously for provenance and governance: when the base definition stays pristine and changes are expressed as overlays, you can trace exactly what’s been modified, by whom, and why, rather than losing that history in a tangle of direct edits to the base. Overlays make the relationship between the canonical definition and its specializations explicit and governable.
The specialization use case is where Overlays show their real power, and I found a compelling example in domains. I wrote in 2025 about using OpenAPI Overlays to express specialization within domains — using banking’s BIAN service domains as the example, where a base API definition can be specialized for different operating models, regulatory regimes, or technological contexts through overlays. This is the pattern that makes Overlays so useful in complex, multi-domain organizations: you have a base definition representing a shared capability, and you apply overlays to specialize it for each domain’s specific needs, without forking the base or maintaining many divergent copies. The overlay captures the specialization declaratively, as a layer, which keeps the relationship between the general and the specialized clear and maintainable. For organizations dealing with regulatory variation, domain variation, or audience variation, Overlays provide a clean mechanism for managing that variation without definition sprawl.
The relationship to Arazzo and the broader business-alignment specifications is where Overlays fit into a coherent picture, and I’ve argued for them together. I wrote in 2025 that we need more APIOps cycles, Arazzo, and OpenAPI Overlays — grouping Overlays with the specifications that address genuine business alignment and operational needs. Overlays and Arazzo are complementary: Arazzo describes workflows that sequence operations into outcomes, while Overlays apply targeted specialization to definitions. Both extend the OpenAPI ecosystem toward the practical needs of real organizations rather than chasing hype. My conversations with Lorna Mitchell, the OpenAPI specification maintainer, about Overlays explored how they bring stakeholders into the API lifecycle — letting different teams contribute their specialized concerns through overlays rather than fighting over a single shared file. This is the collaborative dimension of Overlays: they let multiple stakeholders work on a shared API definition without stepping on each other, each contributing their layer.
Where I land on Overlays is that they’re a quietly important specification that solves a real, widespread problem in how API definitions are maintained at scale. The single-OpenAPI-file-for-everything approach breaks down in real organizations, where many stakeholders have many concerns and the base definition becomes a contested, overloaded mess. Overlays provide the clean architectural answer: keep the source of truth pristine, express specialization and modification as declarative layers on top, preserve provenance and governability, and let different stakeholders work independently on their concerns. This is the kind of practical, infrastructure-level specification that doesn’t generate hype but genuinely improves how API operations work — which is exactly the kind of thing I’ve argued the API world needs more of, against the noise of the specifications that get more attention but solve less. Overlays connect to my deepest themes about source of truth, provenance, and the layered relationship between canonical definitions and their derivatives, and they give organizations a real tool for managing the specialization and modification that complex API operations inevitably require. The base definition stays clean, the modifications stay traceable, and the stakeholders stay unblocked — which is a genuine and underappreciated contribution to the practical work of maintaining API definitions at scale.
References
- What API Common Schema Are Needed For APIs.json Properties And Overlays
- Expanding The Definition Of Our API Contracts
- API Source Of Truth As Well As The Echoes And Overlays Of That Truth
- We Are Loading Too Much Into Our OpenAPIs
- API Evangelist Conversation With Lorna Mitchell About OpenAPI Overlays
- API Evangelist Conversation With Lorna Mitchell, OpenAPI Specification Maintainer With The OpenAPI Initiative
- Using OpenAPI Overlays To Express Specialization Within Domains
- We Need More APIOps Cycles, Arazzo, Overlays, And We Get MCP And A2A
