What is the OpenAPI Overlay Specification?

What is the OpenAPI Overlay Specification? #

As APIs grow in complexity and API descriptions are shared across multiple consumers, teams, and tools, the need to customize or augment an OpenAPI document without modifying its source becomes increasingly important. The OpenAPI Overlay Specification was designed to solve exactly this problem. It provides a structured, reusable mechanism to apply targeted modifications on top of an existing OpenAPI document, enabling a clean separation between the canonical API description and consumer-specific or deployment-specific customizations.

What Problem Does the Overlay Specification Solve? #

Imagine a team that maintains a single authoritative OpenAPI document describing a large API. Different stakeholders need different views:

  • Internal developers may need the raw technical description with all implementation details.
  • Public documentation portals may require additional examples, descriptions in plain language, and redacted internal endpoints.
  • SDK generators may need specific extension fields or operationId conventions different from the canonical document.
  • Partner integrations may require a subset of endpoints with localized descriptions.

Without a formalized overlay mechanism, teams resort to maintaining multiple diverging copies of the same OpenAPI document — a maintenance nightmare. The Overlay Specification provides a principled alternative: define the base document once, and describe the differences in a separate overlay file that can be applied on top of it as needed.

Structure of an Overlay Document #

An Overlay document is itself a YAML or JSON file with a defined structure. Its top-level fields are:

  • overlay — the version of the Overlay Specification being used (e.g., 1.0.0).
  • info — metadata about the overlay, including title and version.
  • actions — an ordered list of overlay actions to apply.

Each action in the actions array specifies:

  • target — a JSONPath expression identifying which part(s) of the OpenAPI document to modify.
  • update — an object to merge into the matched node(s).
  • remove — a boolean (true) to delete the matched node(s).

Here is a basic example:

overlay: 1.0.0
info:
  title: Public API Overlay
  version: 1.0.0
actions:
  - target: $.info
    update:
      description: "This is the public-facing version of our API."
  - target: $.paths['/internal/admin']
    remove: true

In this example, the overlay replaces the info.description field and removes an internal endpoint before the document is published externally. The base OpenAPI document itself is never touched.

JSONPath-Based Targeting #

The power of overlays comes from their use of JSONPath for targeting. JSONPath is a query language for JSON (and by extension YAML) documents, similar to XPath for XML. It allows you to select single nodes, arrays of nodes, or deeply nested objects using expressive query syntax.

For example:

  • $.paths.* — targets all path items.
  • $.paths.*.*.responses — targets all response objects across all operations.
  • $.components.schemas.User — targets the User schema component.
  • $.paths['/orders'].post.summary — targets the summary of the POST /orders operation.

This flexibility means an overlay can make pinpoint changes to exactly the right parts of a document, without risking unintended side effects.

Overlay Actions: update and remove #

update #

The update action performs a deep merge of the provided object into the matched node. This means keys not mentioned in the update are preserved, while keys that are mentioned are overwritten or added. This is similar to JSON Merge Patch (RFC 7396).

- target: $.paths['/users/{id}'].get
  update:
    summary: "Retrieve a user by their unique identifier"
    x-internal-note: "Cached for 60 seconds"

remove #

The remove action deletes the matched node entirely from the document:

- target: $.paths['/internal/metrics']
  remove: true

This is particularly useful for creating public-facing versions of documents that should not expose internal or administrative endpoints.

Real-World Use Cases #

Multi-Audience Documentation #

A platform serving both internal developers and external partners can maintain one canonical OpenAPI document and define separate overlays for each audience. The external overlay might strip internal endpoints and simplify descriptions, while the internal overlay might add richer technical annotations and link to internal runbooks.

SDK Customization #

SDK generators such as openapi-generator often read x- extension fields to control code generation behavior. Overlays allow teams to inject these extensions into the document at generation time without polluting the canonical spec.

Localization #

An overlay can add or replace description fields in different languages, enabling localized API documentation from a single source without maintaining separate translated documents.

Staged API Releases #

During development, some operations may be marked as experimental or subject to change. An overlay can add appropriate warnings or deprecation notices for staging environments without affecting the production document.

Applying Overlays with Tooling #

The Overlay Specification is a relatively recent addition to the OpenAPI ecosystem. Tooling support is growing rapidly:

  • Redocly CLI — supports the overlay command to apply overlay files during the API lifecycle workflow. It is one of the earliest tools to ship overlay support.
  • openapi-overlay — reference implementations are tracked in the official specification repository.
  • Custom build pipelines — many teams implement overlay application as part of their CI/CD pipeline using scripting languages like Python or Node.js, leveraging JSONPath libraries.

The OAI Overlay Specification repository tracks the official specification, proposals, and tooling implementations.

Relationship to Other OpenAPI Mechanisms #

The Overlay Specification is distinct from other customization mechanisms in OpenAPI:

  • $ref — references are used within a document to reuse components. Overlays operate between documents.
  • Extensions (x- fields) — extensions add non-standard metadata within a document. Overlays can add extensions via update actions.
  • Callbacks and webhooks — these are API behavior descriptions, not document customization mechanisms.

Overlays are designed to complement, not replace, these existing tools.

Versioning and Stability #

As of 2025, the Overlay Specification reached version 1.0.0, making it a stable part of the broader OpenAPI tooling ecosystem. Teams evaluating overlays for production use should consult the official specification and confirm tooling compatibility before adopting it in critical workflows.

Conclusion #

The OpenAPI Overlay Specification addresses a genuine pain point in API lifecycle management: the need to customize and extend API descriptions for different contexts without fragmenting the source of truth. By using a simple, JSONPath-driven action model, overlays make it possible to maintain a single canonical OpenAPI document while producing any number of tailored views for documentation portals, SDK generators, partner integrations, and more. As tooling support matures, overlays are poised to become a standard part of professional API workflow pipelines.

Last updated on April 29, 2026.

This website is not affiliated with the OpenAPI Initiative.