OpenAPI Overlay Specification

The OpenAPI Overlay Specification defines a repeatable, machine-readable way to apply a set of changes to an OpenAPI description without editing the original document. An Overlay is its own file that targets nodes in a source description using JSONPath and then updates or removes them, so the base contract stays untouched while a separate, versioned document carries the modifications. It closes a long-standing gap: how do you enrich, correct, or specialize an API description you may not own or want to fork?

• Non-destructive by design - Changes live in a separate Overlay document, leaving the original OpenAPI description authoritative and unmodified.
• Targeted with JSONPath - Each action selects the exact nodes it acts on, then updates or removes them with surgical precision.
• Repeatable and programmatic - The same Overlay can be re-applied across versions and pipelines, making transformations deterministic rather than manual.
• Composable - Multiple Overlays can stack for different audiences or environments — examples, translations, redaction, vendor extensions.

In real API operations Overlays turn a single source-of-truth description into many purpose-built views without ever forking it. Teams apply them in the pipeline to add examples for documentation, inject translations for localized portals, strip fields for compliance and redaction, or correct a brownfield spec they can’t change upstream. Because the transformations are deterministic and versioned, they fit cleanly into CI/CD, and as agents increasingly consume OpenAPI directly, Overlays become the mechanism for tailoring exactly what a given consumer — human or machine — is allowed to see.