Overlay Specification 1.1.0: copy/move actions, primitive u…

Overlays are the OpenAPI ecosystem's answer to a recurring problem: how do you ship one canonical API description but apply structured per-environment, per-region, or per-customer edits without forking the whole file? The Overlay Specification was the first formal answer; 1.1.0 is the iteration that addresses the rough edges teams hit in real use.

Overlay 1.1 Released!

TL;DR

`copy` action — copy or move nodes inside the target document.
Primitive-friendly `update` — target strings, numbers, and other scalars without replacing the whole parent object.
JSONPath updated to RFC 9535 alignment — overlay tools no longer diverge from modern JSONPath implementations.
`description` added to the Overlay info object.
File naming guidance for tooling consistency.

What overlays solve

Imagine a canonical OpenAPI document for an API that deploys to three environments: production, staging, and a partner sandbox. Each environment has differences:

Different server URLs.
Different rate limits documented in the response.
Different auth flows (production uses OAuth, sandbox accepts a static token).
Different examples (production examples shouldn't reference real customer IDs).

Without overlays, you have three options: maintain three copies of the document (drift); bake conditional logic into a generator (fragile); or run a postprocess script (untyped, unreviewed). Overlays formalize the patch-layer approach: one canonical document plus a small overlay file per environment.

The `copy` action

The most useful new action. Previously, if you wanted to apply the same edit to many operations (e.g., add a 429 response to every operation under /orders/*), you wrote the action many times. v1.1 lets you author the response once and copy it across operations:

overlay: 1.1.0
info:
  title: Add common rate-limit response
  version: 1.0.0
actions:
  - target: $.paths.*.*.responses
    update:
      '429':
        $ref: '#/components/responses/RateLimited'

For move semantics — relocate a node from one place to another rather than copying it — copy carries a remove flag that turns the operation into a move. Useful when you've outgrown an organizational structure and want to refactor a canonical spec without editing it directly.

Primitive-friendly `update`

Earlier versions of update replaced whole objects. If you wanted to change a single field's description, you had to write out the entire schema:

# v1.0 — verbose
update:
  type: string
  format: email
  description: User's email address (changed)
  example: [email protected]

v1.1 lets primitive updates target the scalar directly:

# v1.1 — targeted
target: $.components.schemas.User.properties.email.description
update: "User's email address (changed)"

The change matters more than it looks. Overlays should be diffs, not "replace-the-whole-thing-and-hope-the-rest-stayed-the-same". Targeting primitives directly keeps the diff shape focused.

JSONPath: RFC 9535 alignment

JSONPath was historically a de facto standard — implementations agreed on most of the syntax but diverged on edges (filter expressions, slice notation, function calls). RFC 9535 is the formal IETF specification, published in early 2024.

Overlay 1.1 aligns its JSONPath behavior with RFC 9535. Two practical effects:

Cross-tool consistency. A target expression that works in tool A works in tool B.
Modern features. RFC 9535 includes filter expressions, function extensions, and well-defined behavior for edge cases (missing keys, type mismatches).

If you wrote overlays against an earlier draft of JSONPath, scan your target expressions; most are unchanged, but the edge cases that previously "kind of worked" may need explicit fixes.

`description` on info

A small addition: the Overlay info object can now carry a description, separate from the document title and version. Useful when an overlay's purpose isn't obvious from its name:

overlay: 1.1.0
info:
  title: EU GDPR compliance overlay
  version: 1.0.0
  description: |
    Adds GDPR-required disclaimers to data-collection operations and
    documents the EU-specific data retention policy on customer schemas.

For teams maintaining many overlays, this becomes the natural place to document why an overlay exists.

File naming guidance

The spec adds explicit guidance on file extensions and naming patterns so tooling can detect overlays consistently:

.openapi-overlay.yaml / .openapi-overlay.json — recommended.
.overlay.yaml — accepted alternative.
File detection tools should look for the overlay: <version> key rather than relying on extension alone.

Migration from 1.0

v1.1 is backward compatible with 1.0. Existing overlays continue to work. To opt into new features:

Replace verbose object-level updates with primitive-targeted updates where appropriate.
Use `copy` for repeated edits across many operations.
Update target expressions if you used quirks of pre-RFC-9535 JSONPath.
Add `description` to overlay info blocks for documentation.

Where this connects

The OpenAPI 3.2 release post covers the canonical document side; overlays are the patch-layer companion. The February 2026 OAI newsletter summarizes these changes for a broader audience and ties them into the OpenAPI Initiative's roadmap.

References

Source / further reading: OAI Overlay Specification (GitHub)

Overlay Specification 1.1.0: copy/move actions, primitive updates, RFC 9535 JSONPath