OpenAPI Overlays

OpenAPI Overlays are an auxiliary standard that complements the OpenAPI Specification, defined by the same OpenAPI Initiative. Where an OpenAPI description captures the shape of an API — its operations, data structures, and metadata — an Overlay is a separate document that lists a repeatable series of changes to apply to that description. It lets you transform, enrich, and specialize a spec as part of your API workflows without ever touching the original file.

• A companion to OpenAPI - Overlays never stand alone; they always target and transform an existing OpenAPI description.
• Repeatable, ordered changes - Each Overlay is a list of actions applied in sequence, so the same transformation runs deterministically every time.
• Workflow-friendly - Because Overlays are just files, they slot into build pipelines and version control alongside the specs they modify.
• Many views from one source - Documentation, localization, redaction, and vendor-specific variants all derive from a single authoritative description.

In practice Overlays are how teams keep one canonical OpenAPI description while still serving many audiences and stages of the lifecycle. A pipeline applies overlays to add examples for docs, generate test fixtures and mocks, produce compliance and redaction profiles, or correct a brownfield spec without upstream access — each concern isolated in its own file. As the tooling ecosystem matures across open-source and commercial services, and as agents consume these descriptions directly, Overlays are becoming the standard seam for tailoring an API contract to exactly what a given consumer needs to see. See the OpenAPI Overlay Specification for the formal definition.