Overlays solve a problem that had been quietly getting worse: we load too much into our OpenAPIs. The base definition ends up carrying documentation prose, marketing copy, gateway configuration, governance metadata, per-market localization, per-partner specialization, and examples for six audiences — all in one file that everyone has to edit and nobody fully owns.
An Overlay is a separate document containing a list of targeted actions applied to a base OpenAPI: update this description, add these examples, remove these internal endpoints, inject this extension. The source stays pristine, and each concern lives in its own layer.
The uses that pay off immediately: stripping internal-only operations before publishing externally, adding rich examples without cluttering the contract, localizing descriptions, applying partner-specific or market-specific specialization to a shared base, and injecting governance or lifecycle metadata as part of the pipeline rather than asking developers to maintain it by hand.
The mental model I use is source of truth versus the echoes of that truth. The API’s contract is one thing; the many specialized derivations different consumers and contexts need are another. Overlays give you a clean, machine-readable way to derive without forking — and forking is what everyone was doing instead.
