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.1.0).
info — metadata about the overlay, including title and version. As of version 1.1.0, info also accepts an optional description field (CommonMark supported) documenting the overlay’s purpose.
extends — an optional URI reference (absolute or relative) identifying the specific OpenAPI document the overlay is designed to update, such as ./tictactoe.yaml.
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, array, or primitive value to merge into the matched node(s).
remove — a boolean (true) to delete the matched node(s).
copy — a JSONPath expression selecting a node to copy into the matched node(s), added in version 1.1.0.

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.

As of version 1.1.0, the Overlay Specification requires target expressions to be fully compliant with RFC 9535, the formal JSONPath standard, so that overlays remain interoperable across tools. Because some JSONPath libraries predate RFC 9535 or only implement a subset of it, certain filter expressions may need extra parentheses depending on the implementation in use — for example, $.paths.*.get.parameters[?(@.name=='filter' && @.in=='query')] instead of $.paths.*.get.parameters[?@.name=='filter' && @.in=='query'].

Overlay Actions: `update`, `remove`, and `copy` #

`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"

Version 1.1.0 clarified that update also works against primitive-valued nodes directly. For example, targeting a string node and providing a new string replaces it in place:

- target: $.paths['/foo'].get.description
  update: This is the new description

`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. Since version 1.1.0, remove also works against individual primitive entries inside an array, such as deleting a single tag:

- target: $.paths.*.get.tags[?@ == 'dummy']
  remove: true

`copy` #

Introduced in version 1.1.0, the copy action sources its value from elsewhere in the same target document, rather than from a literal value embedded in the overlay. It behaves like update, but the value to merge is selected using another JSONPath expression instead of being written out inline. This makes it possible to duplicate, rename, or move parts of a document.

overlay: 1.1.0
info:
  title: Rename the items path
  version: 1.0.0
actions:
  - target: '$.paths'
    update: { "/new-items": {} }
  - target: '$.paths["/new-items"]'
    copy: '$.paths["/items"]'
  - target: '$.paths["/items"]'
    remove: true
    description: 'moves (renames) the "items" path item to "new-items"'

This sequence first ensures the destination node exists, copies the source node’s contents into it, and then removes the original — effectively renaming /items to /new-items. Because actions are applied in order, copy can be combined with update and remove to implement moves, renames, or duplications that were not possible with update/remove alone.

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, but tooling support has grown quickly. Tools with documented overlay support include:

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.
Bump.sh CLI and Speakeasy CLI — apply overlays as part of broader API documentation and SDK generation workflows.
overlays-js and overlay-jvm — JavaScript and JVM libraries for applying overlays programmatically.
apigee-go-gen, openapi-format, and oas-patch — CLI utilities that include overlay application as part of larger OpenAPI transformation toolchains.
oas-overlay-java, Specmatic, BinkyLabs.OpenApi.Overlays (.NET), Legba (Clojure), and Zuplo CLI — additional language- and platform-specific implementations.
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 an up-to-date list of 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.

Practical Guides: How to Use OpenAPI Overlays #

Overlays unlock a wide range of practical workflows. The guides below walk through specific, real-world applications in depth:

Versioning and Stability #

The Overlay Specification reached its first stable release, version 1.0.0, in October 2024. It has since been updated to version 1.1.0, published 14 January 2026, which added the copy action, an Info.description field, explicit support for updating and removing primitive-valued nodes, a recommended purpose.overlay.yaml file naming convention, and a requirement that target expressions be fully RFC 9535-compliant JSONPath. Teams upgrading existing overlays should consult the official upgrade guide. Teams evaluating overlays for production use should consult the latest 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 July 22, 2026.