The Overlay Specification is a companion to the [OpenAPI] Specification.
An Overlay describes a set of changes to be applied or “overlaid” onto an existing OpenAPI description.
The main purpose of the Overlay Specification is to provide a way to repeatably apply transformations to one or many OpenAPI descriptions. Use cases include updating descriptions, adding metadata to be consumed by another tool, or removing certain elements from an API description before sharing it with partners. An Overlay may be specific to a single OpenAPI description or be designed to apply the same transform to any OpenAPI description.
The Overlay Specification is versioned using a major.minor.patch versioning scheme. The major.minor portion of the version string (for example 1.0) SHALL designate the Overlay feature set. patch versions address errors in, or provide clarifications to, this document, not the feature set. The patch version SHOULD NOT be considered by tooling, making no distinction between 1.0.0 and 1.0.1 for example.
Note: Version 1.0.0 of the Overlay Specification was released after spending some time in draft and being implemented by a few early-adopting tool providers. Check with your tool provider for the details of what is supported in each tool.
Implementations MUST check all possible target [OpenAPI] Description documents provided to the implementation before treating an extends value as unresolvable.
To ensure portability, when a target [OpenAPI] Description defines $self, the Overlay’s extends value SHOULD match the target’s $self URI.
URIs used in an Overlay document, including $self and extends, are identifiers, and not necessarily locators (URLs).
Unless specified otherwise, all fields that are URI references MAY be relative references as defined by RFC3986 Section 4.2.
Relative URI references are resolved using the appropriate base URI, which MUST be determined in accordance with RFC3986 Section 5.1.1 - 5.1.4.
The base URI for resolving relative references within an Overlay document is determined as follows:
- If the
$self field is present and is an absolute URI, the base URI is the $self URI (per RFC3986 Section 5.1.1: Base URI Embedded in Content).
- If the
$self field is present and is a relative URI-reference, it MUST first be resolved against the next possible base URI source per RFC3986 Section 5.1.2 - 5.1.4 before being used as the base URI for resolving other relative references.
- If the
$self field is not present, the base URI MUST be determined from the next possible base URI source per RFC3986 Section 5.1.2 - 5.1.4.
The most common base URI source in this case is the retrieval URI of the Overlay document (per RFC3986 Section 5.1.3), though other sources such as encapsulating entities (RFC3986 Section 5.1.2) or application-specific defaults (RFC3986 Section 5.1.4) MAY apply.
For Overlay Object fields that identify whole documents ($self and extends), fragment identifiers MUST NOT be used.
Relative references in CommonMark hyperlinks (such as those in description fields) are resolved in their rendered context, which might differ from the context of the Overlay document.
In the following description, if a field is not explicitly REQUIRED or described with a MUST or SHALL, it can be considered OPTIONAL.
This is the root object of the Overlay.
| Field Name |
Type |
Description |
| overlay |
string |
REQUIRED. This string MUST be the version number of the Overlay Specification that the Overlay document uses. The overlay field SHOULD be used by tooling to interpret the Overlay document. |
| $self |
string |
A URI-reference for the Overlay document. This string MUST be in the form of a URI-reference as defined by RFC3986 Section 4.1. When present, this field provides the self-assigned URI of this Overlay document, which also serves as its base URI in accordance with RFC3986 Section 5.1.1 for resolving relative references within this document. The $self URI MUST NOT contain a fragment identifier. Overlay documents MAY include a $self field to ensure portable, unambiguous reference resolution. |
| info |
Info Object |
REQUIRED. Provides metadata about the Overlay. The metadata MAY be used by tooling as required. |
| extends |
string |
URI reference that identifies the target document (such as an [OpenAPI] document) this overlay applies to. |
| actions |
[Action Object | Reusable Action Reference Object] |
REQUIRED An ordered list of actions to be applied to the target document. The array MUST contain at least one value. |
| components |
Components Object |
A set of components to reuse across the Overlay Document. |
This object MAY be extended with Specification Extensions.
The list of actions MUST be applied in sequential order to ensure a consistent outcome. Actions are applied to the result of the previous action. This enables objects to be deleted in one action and then re-created in a subsequent action, for example.
The extends property can be used to indicate that the Overlay was designed to update a specific [OpenAPI] description.
Where no extends is provided it is the responsibility of tooling to apply the Overlay document to the appropriate OpenAPI description(s).
In the following example, the Overlay identifies a target OpenAPI description using an absolute URI:
overlay: 1.2.0
info:
title: Overlay for the Tic Tac Toe API document
version: 1.0.0
extends: 'https://api.example.com/openapi/tictactoe.yaml'
...
In the following example, the Overlay document also includes $self, which establishes the document’s identity and base URI:
overlay: 1.2.0
$self: 'https://example.com/overlays/tictactoe.overlay.yaml'
info:
title: Overlay for the Tic Tac Toe API document
version: 1.0.0
extends: 'https://api.example.com/openapi/tictactoe.yaml'
...
The extends property can also specify a relative URI reference.
Relative extends values are resolved using the base URI rules in Relative References in URIs:
overlay: 1.2.0
$self: 'https://example.com/overlays/tictactoe.overlay.yaml'
info:
title: Overlay for the Tic Tac Toe API document
version: 1.0.0
extends: '../openapi/tictactoe.yaml'
With the above Overlay document, extends resolves to https://example.com/openapi/tictactoe.yaml.
The object provides metadata about the Overlay.
The metadata MAY be used by the clients if needed.
| Field Name |
Type |
Description |
| title |
string |
REQUIRED. A human readable description of the purpose of the overlay. |
| version |
string |
REQUIRED. A version identifier for indicating changes to the Overlay document. |
| description |
string |
A description of the Overlay Document. [CommonMark] syntax MAY be used for rich text representation. |
This object MAY be extended with Specification Extensions.
The object provides a set of components to be reused across the Overlay document.
When a key under components.actions is referenced by a Reusable Action Reference Object, that key is part of a JSON Pointer token and MUST be encoded according to [RFC6901], Section 3 (for example, ~ as ~0 and / as ~1).
This object MAY be extended with Specification Extensions.
This object represents one or more changes to be applied to the target document at the locations defined by the target JSONPath expression.
| Field Name |
Type |
Description |
| target |
string |
REQUIRED A RFC9535 JSONPath query expression selecting nodes in the target document. |
| description |
string |
A description of the action. [CommonMark] syntax MAY be used for rich text representation. |
| update |
Any |
If the target selects object nodes, the value of this field MUST be an object with the properties and values to merge with each selected object. If the target selects array nodes, the value of this field MUST be an array to concatenate with each selected array, or an object or primitive value to append to each selected array. If the target selects primitive nodes, the value of this field MUST be a primitive value to replace each selected node. This field has no impact if the remove field of this action object is true or if the copy field contains a value. |
| copy |
string |
A JSONPath expression selecting a single node to copy into the target nodes. If the target selects object nodes, the value of this field MUST be an object with the properties and values to merge with each selected object. If the target selects array nodes, the value of this field MUST be an array to concatenate with each selected array, or an object or primitive value to append to each selected array. If the target selects primitive nodes, the value of this field MUST be a primitive value to replace each selected node. This field has no impact if the remove field of this action object is true or if the update field contains a value. |
| remove |
boolean |
A boolean value that indicates that each of the target nodes MUST be removed from the the map or array it is contained in. The default value is false. |
If the target JSONPath expression selects zero nodes, the action succeeds without changing the target document.
If the target JSONPath expression selects two or more nodes for an update or copy action, the selected nodes MUST be either all objects or all arrays or all primitives.
The properties of the update or copy object MUST be compatible with the target object referenced by the JSONPath key. When the Overlay document is applied, the update or copy object is merged with the target object by recursively applying these steps:
- A property that only exists in the target object is left unchanged.
- A property that only exists in the
update or copy object is inserted into the target object.
- If a property exists in both
update or copy and target object:
- A primitive value of the
update or copy property replaces a primitive value of the target property.
- An array value of the
update or copy property is concatenated with an array value of the target property.
- An object value of the
update or copy property is recursively merged with an object value of the target property.
- Other property value combinations are incompatible and result in an error.
This object MAY be extended with Specification Extensions.
This object defines a reusable action in components.actions.
It can be referenced from actions by a Reusable Action Reference Object.
| Field Name |
Type |
Description |
| description |
string |
A description of the reusable action. This description is independent of the description field on the contained Action Object and is intended to document the reusable action itself (for example, its purpose or usage). [CommonMark] syntax MAY be used for rich text representation. |
| fields |
Action Object |
An Action Object where no field is required, except that the target field MUST NOT be provided. The target MUST be supplied by the Reusable Action Reference Object. |
This object MAY be extended with Specification Extensions.
A reusable action is similar to an action but differs in important ways:
- Action fields are nested inside the
fields property, not defined as peer properties. The fields object may omit any action field, and MUST NOT include the target field; the target MUST be supplied by the Reusable Action Reference Object.
- A Reusable Action Object has to be referenced by a Reusable Action Reference Object to have any effect on the OpenAPI description.
A Reusable Action Reference Object applies a reusable action defined in components.actions to a specific target in the source document.
It references the reusable action by $ref and MAY provide action fields that override values from the referenced reusable action for that use.
| Field Name |
Type |
Description |
| $ref |
string |
REQUIRED A same-document (or fragment-only) relative URI reference, per RFC3986 §4.4, where the fragment syntax is JSON Pointer with the pointer prefix restricted to /components/actions/. Component action keys in this pointer MUST be encoded according to [RFC6901], Section 3. |
| target |
string |
REQUIRED A JSONPath query expression, as described in [RFC9535], referencing the target objects in the source document. |
| description |
string |
A description of the action. [CommonMark] syntax MAY be used for rich text representation. |
This object MAY be extended with Specification Extensions.
In case a description is defined in fields of the referenced Reusable Action Object and in the Reusable Action Reference Object, the description from the Reusable Action Reference Object MUST be used.
When updating properties throughout the target document it may be more efficient to create a single Action Object that mirrors the structure of the target document. e.g.
overlay: 1.2.0
info:
title: Structured Overlay
version: 1.0.0
actions:
- target: '$'
update:
info:
x-overlay-applied: structured-overlay
paths:
'/':
summary: 'The root resource'
get:
summary: 'Retrieve the root resource'
x-rate-limit: 100
'/pets':
get:
summary: 'Retrieve a list of pets'
x-rate-limit: 100
components:
tags:
Alternatively, where only a small number of updates need to be applied to a large document, each Action Object MAY be more targeted.
overlay: 1.1.0
info:
title: Targeted Overlay
version: 1.0.0
actions:
- target: $.paths['/foo'].get.description
update: This is the new description
- target: $.paths['/bar'].get.description
update: This is the updated description
- target: $.paths['/bar']
update:
post:
description: This is an updated description of a child object
x-safe: false
One significant advantage of using the JSONPath syntax is that it allows referencing multiple nodes in the target document. This would allow a single update object to be applied to multiple target objects using wildcards and other multi-value selectors.
overlay: 1.2.0
info:
title: Update many objects at once
version: 1.0.0
actions:
- target: $.paths.*.get
update:
x-safe: true
- target: $.paths.*.get.parameters[?@.name=='filter' && @.in=='query']
update:
schema:
$ref: '#/components/schemas/filterSchema'
Array elements can be added using the update action.
overlay: 1.2.0
info:
title: Add an array element
version: 1.0.0
actions:
- target: $.paths.*.get.parameters
update:
name: newParam
in: query
Array elements can be deleted using the remove action. Use of array indexes to remove array items should be avoided where possible as indexes will change when items are removed.
overlay: 1.2.0
info:
title: Remove an array element
version: 1.0.0
actions:
- target: $.paths.*.get.parameters[?@.name == 'dummy']
remove: true
This also works for primitive target nodes:
overlay: 1.1.0
info:
title: Remove a primitive array element
version: 1.0.0
actions:
- target: $.paths.*.get.tags[?@ == 'dummy']
remove: true
By annotating a target document (such as an [OpenAPI] document) using Specification Extensions such as x-oai-traits, the author of the target document MAY identify where overlay updates should be applied.
openapi: 3.2.0
info:
title: API with a paged collection
version: 1.0.0
paths:
/items:
get:
x-oai-traits: ['paged']
responses:
200:
description: OK
/items/{id}/subitems:
get:
x-oai-traits: ['paged']
parameters:
- name: id
in: path
required: true
responses:
200:
description: OK
/other:
get:
responses:
200:
description: OK
With the above OpenAPI document, the following Overlay document will apply the necessary updates to describe how paging is implemented, where that trait has been applied.
overlay: 1.2.0
info:
title: Apply Traits
version: 1.0.0
actions:
- target: $.paths[?(@.get['x-oai-traits'][?(@ == 'paged')])].get
update:
parameters:
- name: top
in: query
- name: skip
in: query
resulting in
openapi: 3.2.0
info:
title: API with a paged collection
version: 1.0.0
paths:
/items:
get:
x-oai-traits: ["paged"]
responses:
200:
description: OK
parameters:
- name: top
in: query
- name: skip
in: query
/items/{id}/subitems:
get:
x-oai-traits: ["paged"]
parameters:
- name: id
in: path
required: true
- name: top
in: query
- name: skip
in: query
responses:
200:
description: OK
/other:
get:
responses:
200:
description: OK
This approach allows inversion of control as to where the Overlay updates apply to the target document itself.
Copy actions behave similarly to update actions but source the new values to merge with the target from the document being transformed instead of providing them in the Overlay document. Copy actions MAY be used in sequence with update or remove actions to perform more advanced transformations like moving or renaming nodes.
This example shows how to copy all operations from the items path item to the some-items path item.
openapi: 3.2.0
info:
title: Example API
version: 1.0.0
paths:
/items:
get:
responses:
200:
description: OK
/some-items:
delete:
responses:
200:
description: OK
overlay: 1.1.0
info:
title: Copy contents of an existing path to a new location
version: 1.0.0
actions:
- target: '$.paths["/some-items"]'
copy: '$.paths["/items"]'
description: 'copies recursively all elements from the "items" path item to the new "some-items" path item without ensuring the node exists before the copy'
openapi: 3.2.0
info:
title: Example API
version: 1.0.0
paths:
/items:
get:
responses:
200:
description: OK
/some-items:
get:
responses:
200:
description: OK
delete:
responses:
200:
description: OK
This example shows how to copy all operations from the items path item to the other-items path item after first ensuring the target exists with an update action.
openapi: 3.2.0
info:
title: Example API
version: 1.0.0
paths:
/items:
get:
responses:
200:
description: OK
/some-items:
delete:
responses:
200:
description: OK
overlay: 1.1.0
info:
title: Create a path and copy the contents of an existing path to the new path
version: 1.0.0
actions:
- target: '$.paths'
update: { "/other-items": {} }
- target: '$.paths["/other-items"]'
copy: '$.paths["/items"]'
description: 'copies recursively all elements from the "items" path item to the new "other-items" path item while ensuring the node exists before the copy'
openapi: 3.2.0
info:
title: Example API
version: 1.0.0
paths:
/items:
get:
responses:
200:
description: OK
/other-items:
get:
responses:
200:
description: OK
/some-items:
delete:
responses:
200:
description: OK
This example shows how to rename the items path item to new-items using a sequence of overlay actions:
- Use an
update action to ensure the target path item exists.
- Use a
copy action to copy the source path item to the target.
- Use a
remove action to delete the original source path item.
openapi: 3.2.0
info:
title: Example API
version: 1.0.0
paths:
/items:
get:
responses:
200:
description: OK
/some-items:
delete:
responses:
200:
description: OK
overlay: 1.1.0
info:
title: Update the path for an API endpoint
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"'
openapi: 3.2.0
info:
title: Example API
version: 1.0.0
paths:
/new-items:
get:
responses:
200:
description: OK
/some-items:
delete:
responses:
200:
description: OK
This example shows how a reusable action can provide shared update content while a reusable action reference supplies the target locally. In this case, each reference reuses the same error response definition but supplies a different target so the update is applied to different operations.
openapi: 3.2.0
info:
title: Example API
version: 1.0.0
paths:
/items:
get:
responses:
200:
description: OK
/some-items:
delete:
responses:
200:
description: OK
overlay: 1.2.0
info:
title: Use reusable actions to insert error responses
version: 1.0.0
components:
actions:
errorResponse:
fields:
update:
404:
description: Not Found
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Adds an error response to the operation
actions:
- $ref: '#/components/actions/errorResponse'
target: "$.paths['/items'].get.responses"
- $ref: '#/components/actions/errorResponse'
target: "$.paths['/some-items'].delete.responses"
openapi: 3.2.0
info:
title: Example API
version: 1.0.0
paths:
/items:
get:
responses:
200:
description: OK
404:
description: Not Found
content:
application/json:
schema:
type: object
properties:
message:
type: string
/some-items:
delete:
responses:
200:
description: OK
404:
description: Not Found
content:
application/json:
schema:
type: object
properties:
message:
type: string
While the Overlay Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
The extension properties are implemented as patterned fields that are always prefixed by "x-".
| Field Pattern |
Type |
Description |
| ^x- |
Any |
Allows extensions to the Overlay Specification. The field name MUST begin with x-, for example, x-internal-id. Field names beginning x-oai- and x-oas- are reserved for uses defined by the OpenAPI Initiative. The value MAY be null, a primitive, an array or an object. |
The extensions may or may not be supported by the available tooling, but those may be extended as well to add requested support (if tools are internal or open-sourced).
Overlay files MAY choose to follow the convention of a purpose.overlay.yaml file naming pattern.
Other file naming conventions are also supported.
[RFC9535] is a recent specification and libraries implementing JSONPath support might predate the RFC. Those libraries might differ entirely (expressions syntax is incompatible), or implement additional capabilities (superset of the RFC). A tool or library MUST fully implement [RFC9535] when parsing and expanding JSONPath query expressions to be compliant with the Overlay specification.
Interoperable Overlay Documents MUST use RFC9535 JSONPath query expressions and MUST NOT use tool-specific JSONPath extensions.
This appendix provides concrete examples demonstrating how the $self field, Source Description URLs, and relative references work together across different deployment scenarios.
Assume the following Overlay document is retrieved from file:///Users/dev/projects/overlays/purchase.overlay.yaml:
overlay: 1.2.0
$self: https://example.com/overlays/purchase.overlay.yaml
info:
title: Purchase overlay
version: 1.0.0
extends: ../openapi/petstore.yaml
actions:
- target: '$.info'
update:
x-overlay: purchase
The relative extends URI ../openapi/petstore.yaml resolves against the $self base URI https://example.com/overlays/purchase.overlay.yaml, producing https://example.com/openapi/petstore.yaml, regardless of the retrieval URI.
If the same Overlay document does not define $self:
overlay: 1.2.0
info:
title: Purchase overlay
version: 1.0.0
extends: ../openapi/petstore.yaml
actions:
- target: '$.info'
update:
x-overlay: purchase
Retrieved from file:///Users/dev/projects/overlays/purchase.overlay.yaml, the relative extends URI resolves to file:///Users/dev/projects/openapi/petstore.yaml.
Per RFC3986 Section 5.1.2, the base URI can be provided by an encapsulating entity. For example, in a multipart/related response where an Overlay document is embedded:
Content-Type: multipart/related; boundary=example; type=application/json
--example
Content-Type: application/json
Content-Location: https://example.com/overlays/purchase.overlay.json
{
"overlay": "1.2.0",
"info": {"title": "Purchase overlay", "version": "1.0.0"},
"extends": "../openapi/petstore.json",
"actions": [
{
"target": "$.info",
"update": {"x-overlay": "purchase"}
}
]
}
--example--
The Content-Location header provides the base URI (https://example.com/overlays/purchase.overlay.json), so ../openapi/petstore.json resolves to https://example.com/openapi/petstore.json even without a $self field.
Per RFC3986 Section 5.1.4, applications may define default base URIs. For documents loaded without explicit retrieval URIs (e.g., from a database), implementations typically generate a unique base URI per document using a fixed prefix plus a unique identifier.
For example, an API management platform might construct base URIs as https://overlays.example.com/{uuid} for each document:
overlay: 1.2.0
info:
title: Purchase overlay
version: 1.0.0
extends: specs/petstore.yaml
actions:
- target: '$.info'
update:
x-overlay: purchase
If the application assigns base URI https://overlays.example.com/a7b3c4d5 to this document, then specs/petstore.yaml resolves to https://overlays.example.com/specs/petstore.yaml.
When $self is itself a relative URI-reference, it must be resolved before being used as a base URI:
overlay: 1.2.0
$self: overlays/purchase.overlay.yaml
info:
title: Purchase overlay
version: 1.0.0
extends: ../openapi/petstore.yaml
actions:
- target: '$.info'
update:
x-overlay: purchase
Retrieved from https://example.com/v2/api-description.yaml:
- First, resolve the
$self relative reference overlays/purchase.overlay.yaml against the retrieval URI https://example.com/v2/api-description.yaml, which resolves to https://example.com/v2/overlays/purchase.overlay.yaml per RFC3986 Section 5.2.
- Then resolve the
extends relative reference ../openapi/petstore.yaml against the resolved $self base URI https://example.com/v2/overlays/purchase.overlay.yaml, which resolves to https://example.com/v2/openapi/petstore.yaml.
An Overlay may be given this extends value:
overlay: 1.2.0
info:
title: Overlay for approved API description
version: 1.0.0
extends: https://apis.example.com/approved/petstore.yaml
actions:
- target: '$.info'
update:
x-overlay: approved
A candidate target OpenAPI description might be retrieved from https://cdn.example.net/mirror/petstore.yaml while declaring:
openapi: 3.2.0
$self: https://apis.example.com/approved/petstore.yaml
info:
title: Petstore
version: 1.0.0
paths: {}
Because extends is identifier-based, the match succeeds using the target description’s $self URI, even though retrieval occurred from a different location.
4.10 Comments in OpenAPI Descriptions
Some formats, like YAML or JSONC, support using comments which do not impact the semantic meaning of the description. Applying Overlay Actions to a description MAY result in the loss of such comments in the updated description. The exact behavior is specific to the tool implementing the Overlay Specification.