Wiki · Concept · Last reviewed June 25, 2026

Overlay Specification

The OpenAPI Overlay Specification is a companion standard for applying repeatable changes to OpenAPI descriptions while keeping those changes separate from the source API document.

Category: Concept / API Governance Updated: June 25, 2026 Tags: Overlay, OpenAPI, API governance, JSONPath, agents

Definition

The OpenAPI Overlay Specification defines a document format for information that transforms an existing OpenAPI Specification description while remaining separate from the OpenAPI source document. The OpenAPI Initiative publications page lists Overlay v1.1.0 and v1.0.0 as specification versions; the v1.1.0 specification revision history dates the 1.1.0 release to January 14, 2026.

An Overlay is best understood as a repeatable change layer. Instead of editing a generated OpenAPI file directly, an organization can keep a separate overlay that adds partner-facing descriptions, removes internal endpoints, copies common responses across operations, applies gateway metadata, or changes deployment-specific fields. The point is not to create a second API. The point is to make controlled transformations visible, reviewable, and reusable.

Mechanism

An Overlay document is a JSON object that may be represented in JSON or YAML. The root Overlay Object includes an overlay version string, an info object, an optional extends URI reference for the target document, and an ordered actions array. The specification requires actions to be applied sequentially, with each action operating on the result of the previous action.

Each Action Object has a target and a modifier. The target is an RFC 9535 JSONPath query expression that identifies elements in the target OpenAPI description. The modifier determines what happens there: update, remove, or copy. Overlay v1.1.0 added the copy property and improved support for updating primitive values such as strings and integers. It also updated the specification for full RFC 9535 JSONPath compliance.

This makes Overlay a pipeline artifact. A source OpenAPI document can remain close to code generation or service ownership, while overlays can express publication, security, partner, language, or tool-specific transformations downstream.

Agent Context

Agent systems often consume API descriptions through gateways, tool registries, generated SDKs, or Model Context Protocol servers. Overlay matters because the API description that is safe for one consumer may be wrong for another. A developer-facing OpenAPI file may include internal operations, confusing descriptions, missing default responses, or metadata that is useful to a gateway but not to a model-facing tool host.

An overlay can narrow the document before an agent sees it. It can remove operations that should never become tools, add safer descriptions, copy consistent error responses, attach policy metadata, or mark operations that need human approval. This is still not a safety system. It is a disciplined way to make the tool surface derivation explicit instead of hand-editing a separate copy that silently drifts.

Governance Use

For governance, Overlay is a record of transformation. It can answer: which source description was used, which elements were changed, which operations were removed, which metadata was added, which policy layer made the change, and whether the same transformation was applied across multiple services. That matters when an API description feeds documentation, SDK generation, tests, compliance checks, or agent-accessible tools.

The official OpenAPI learning page lists use cases such as translation, deployment-environment configuration, separation of gateway or service-level metadata, traits-like reuse of parameters or headers, default responses or parameters, and global configuration based on filter conditions. Those use cases are ordinary API lifecycle work, but they become higher stakes when the resulting description shapes automated action.

Limits

Overlay does not prove that the target OpenAPI description is correct, that a transformation is appropriate, or that the resulting document is safe for agent execution. A valid overlay can remove too much, copy stale metadata, hide an operation that auditors need to see, or add descriptions that make a tool look safer than it is.

It also depends on tooling. The specification says compliant tools must fully implement RFC 9535 when parsing and expanding JSONPath expressions. Older JSONPath libraries may behave differently. If an organization treats overlays as policy, it must test the exact toolchain that applies them, preserve outputs, and watch for semantic drift between the source description, overlay, transformed document, generated clients, and deployed service.

Review Record

Source Discipline

Claims about Overlay should cite the exact specification version and distinguish the source OpenAPI document from the overlay and the transformed result. Claims about current versions and schema iterations should use the OpenAPI Initiative publications page. Claims about v1.1.0 features such as copy, primitive updates, and RFC 9535 alignment should cite OpenAPI Initiative materials rather than vendor summaries.

Spiralist Reading

Spiralism reads Overlay as annotation with consequence. A small file can decide what an agent sees, what a partner receives, or what an SDK believes. That power should be visible. The healthy posture is not "the spec changed"; it is "this overlay changed the spec for this audience, for this reason, under this review."

Sources

Return to Wiki