Wiki · Concept · Last reviewed July 1, 2026

Overlay Specification

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

Category: Concept / API Governance Published: June 25, 2026 Modified: July 1, 2026 Last reviewed: July 1, 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 result is a transformed OpenAPI description, not a second live API. The governance value is that the source description, overlay, transformed result, and downstream tool mapping can be reviewed as distinct artifacts.

Current Context

As of July 1, 2026, the OpenAPI Initiative publications page lists Overlay v1.1.0 as a published specification version alongside v1.0.0, with v1.1 schema iterations dated January 14, 2026 and April 1, 2026. The same publications page warns that schemas help catch errors but do not replace the specification text when the two disagree.

Overlay v1.1.0 matters because it tightened the standard around RFC 9535 JSONPath, added the copy modifier, and improved updates to primitive values. The OpenAPI learning documentation frames overlays as deterministic updates across the API lifecycle, including translation, deployment-environment configuration, gateway or SLA metadata, traits-like reuse of parameters or headers, default responses, and conditional global configuration.

This standard sits next to OpenAPI and Arazzo in the agent-tool stack. OpenAPI describes the API surface, Arazzo can describe workflows over that surface, and Overlay can transform the description before it is published to a particular audience or tool host. None of those specifications authorizes a call or proves the service is safe; they provide structured evidence for review.

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 one or more elements in the target OpenAPI description. The modifier determines what happens there: update, remove, or copy. If a target expression selects zero nodes, the specification treats the action as succeeding without changing the document. If it selects multiple nodes for update or copy, those nodes must be compatible object, array, or primitive nodes.

The update modifier merges objects recursively, concatenates arrays, and can replace primitive values. The remove modifier removes selected map or array nodes. The copy modifier, added in v1.1.0, reads one selected node from the document being transformed and merges, appends, or replaces the target nodes according to the same compatibility rules. Because actions run in order, an overlay can first create a target node, then copy into it, then remove the original node.

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. A serious pipeline should validate the source, apply the overlay with a pinned toolchain, validate the transformed document, and preserve the diff.

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 clearer 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.

The OpenAPI Initiative's February 2026 newsletter described work on making OpenAPI more useful for large language models as API clients, including capability discovery and intent signaling. Overlay belongs in that conversation because agent-facing descriptions are often derived views of a broader API. The derived view needs provenance: which OpenAPI file, which overlay, which overlay tool, which validation result, which approval policy, and which final tool contract.

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.

For AI audit trails, Overlay should be treated like reviewed code. The record should include the source OpenAPI hash, overlay hash, tool version, transformed-document hash, validator output, approval record, and the agent or gateway that consumed the result. Without those links, a later incident can identify the final tool description but not the transformation that produced it.

Failure Modes

Defense Pattern

A defensible Overlay workflow pins both inputs and machinery: source OpenAPI document, overlay file, schema or specification version, transformer implementation, validator, and generated output. The transformed document should fail closed if validation fails, if the expected source hash changes, or if a target expression that is supposed to match a known node no longer matches it.

For agent-facing use, the overlay review should be tied to AI change management, agent observability, and agent sandboxing. A transformed OpenAPI file can help narrow what an agent sees, but runtime controls still need to enforce identity, authorization, rate limits, egress boundaries, human approval, and logging.

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

Open Questions

Sources

Return to Wiki