Speakeasy Logo
Skip to Content
OpenAPI HubOverlays

OpenAPI Overlays

Overlays allow us to modify an existing OpenAPI document without directly editing the original document. An overlay is a separate document that contains instructions for updating the original OpenAPI document.

Overlays are useful for:

  • Separating concerns between the original API definition and modifications required by different consumers or use cases.
  • Avoiding direct modification of the original OpenAPI document, which may be managed by a separate team or process.
  • Applying a set of common modifications to multiple OpenAPI documents.

Overlay Document Structure in OpenAPI

An Overlay document is a separate document from the OpenAPI document it modifies. It contains an ordered list of Action Objects that describe the modifications to be made to the original OpenAPI document.

Overlay Document Structure

The following sections describe the structure of an Overlay document:

overlay

Field Name
Type
String
Required

The version of the Overlay Specification that the document uses. The value must be a supported version number

info

Field NameTypeRequired
infoInfo Object

Provides metadata about the Overlay document.

title

Field NameTypeRequired
titleString

A human-readable title describing the purpose of the Overlay document.

version

Field Name
version
Type
String
Required

A version identifier indicating the version of the Overlay document.

actions

Field NameTypeRequired
actions[Action Object]

An ordered list of Action Objects to be applied to the original OpenAPI document. The list must contain at least one Action Object.

target

Field NameTypeRequired
versionString

A JSONPath  expression that specifies the location in the original OpenAPI document where the change should be made. See Action Targets.

description

Field NameTypeRequired
versionString

A description of the action. This may contain CommonMark syntax  to provide a rich description.

update

Field NameTypeRequired
versionString

An object containing the properties and values to be merged with the objects referenced by the target. This field has no effect if the remove field is true.

remove

Field NameTypeRequired
versionString

If true, the objects referenced by the target are removed from the original document. If false or not provided, the objects are not removed. This field takes precedence over the update field.

Field Name
overlay
Type
String
Required
Description
The version of the Overlay Specification that the document uses. The value must be a supported version number.
info
Required
Description
Provides metadata about the Overlay document.
extends
Type
String
Required
Description
A URL to the original OpenAPI document this overlay applies to.
actions
Required
Description
An ordered list of Action Objects to be applied to the original OpenAPI document. The list must contain at least one Action Object.
x-*
Required
Description
Any number of extension fields can be added to the Overlay document that can be used by tooling and vendors. When provided at this level, they apply to the entire Overlay document.

Overlay Specification Versions

The overlay field contains the version number of the Overlay Specification that the document conforms to. Tooling should use this value to interpret the document correctly.

The current version of the Overlay Specification is 1.0.0, but keep in mind that the specification is still under development.

Overlay Info Object in OpenAPI

Provides metadata about the Overlay document.

Field Name
title
Type
String
Required
Description
A human-readable title describing the purpose of the Overlay document.
version
Type
String
Required
Description
A version identifier indicating the version of the Overlay document.
x-*
Type
Any
Required
Description
Any number of extension fields can be added that can be used by tooling and vendors.

Action Object in OpenAPI

Each Action Object represents at least one change to be made to the original OpenAPI document at the location specified by the target field.

Field Name
Type
String
Required
Description
A JSONPath  expression that specifies the location in the original OpenAPI document where the change should be made. See Action Targets.
Type
String
Required
Description
A description of the action. This may contain CommonMark syntax  to provide a rich description.
Type
Any
Required
Description
An object containing the properties and values to be merged with the objects referenced by the
. This field has no effect if the
field is
.
Type
Boolean
Required
Description
If
, the objects referenced by the
are removed from the original document. If
or not provided, the objects are not removed. This field takes precedence over the
field.
Type
Any
Required
Description
Any number of extension fields can be added to the Action Object that can be used by tooling and vendors.

Action Targets in OpenAPI

The target field of an Action Object is a JSONPath  expression that specifies the locations in the original OpenAPI document where the change should be made.

JSONPath expressions allow you to select and manipulate specific parts of a JSON or YAML document using an intuitive syntax. The expressions are similar to XPath for XML, allowing you to traverse the document tree and select elements based on various criteria.

JSONPath is implemented differently  across tooling languages and among individual tools. Speakeasy uses VMware Labs YAML JSONPath  to parse JSONPath.

Here are some examples of JSONPath expressions relevant to OpenAPI documents:

JSONPath Expression
Description
Selects the
field of the
object.
Description
Selects the
field of the first server in the
array.
Description
Selects the
of the
operation on the
path.
Description
Selects all query parameters across all paths.
Description
Selects all operations that have one or more query parameters.
Description
Selects tags of specific operations that have one or more query parameters.
Description
Selects the
schema from the
object.

When selecting the object to target for different types of updates, consider the following:

Type of Update
Updating a primitive value (string, number, boolean)
Target Object
The containing object
Updating an object
Target Object
The object itself
Updating an array
Target Object
The array itself
Adding a new property to an object
Target Object
The object itself
Adding a new item to an array
Target Object
The array itself
Removing a property from an object
Target Object
The object itself
Removing an item from an array
Target Object
The array itself

For example, to update the description field of the info object, you would target the info object itself:

To remove a specific path, such as /oldDrinks, from the paths object, you would target that path directly:

Applying an Overlay in OpenAPI

When an overlay is applied, the update object is merged with the targeted objects. Any properties present in both the update object and the targeted objects will be replaced with the values from the update object. New properties from the update object will be added to the targeted objects.

The Overlay document is processed in the following order:

  1. Tooling locates the original OpenAPI document to modify. This is based on the extends field if provided, otherwise determined by the tooling.

  2. Each Action Object is applied to the OpenAPI documents in the order they appear in the actions array.

    For each action:

    1. The target JSONPath expression is evaluated against the OpenAPI document to locate the objects to modify.

    2. If the remove field is true, the targeted objects are removed from the OpenAPI document.

    3. If the remove field is false or not provided and an update object is specified, the update object is merged with each of the targeted objects.

OpenAPI Overlay Examples

Here are some examples of overlays that could be applied to the Speakeasy Bar OpenAPI document:

Updating Info and Servers

This example demonstrates updating the info and servers objects in the original OpenAPI document.

Adding Tags and Updating Drink Responses

This example demonstrates adding tags to the OpenAPI document and updating response objects for operations related to drinks.

Adding Query Parameter Tags

This example demonstrates adding a tag to all operations that have query parameters.

Removing Deprecated Drink Operations

This example demonstrates removing operations related to drinks that have been marked as deprecated.

Field Name
version
Type
String
Required
Field Name
actions
Required
Field Name
target
Type
String
Required
Description
A JSONPath  expression that specifies the location in the original OpenAPI document where the change should be applied.
description
Type
String
Required
Description
A description of the action. This may contain CommonMark syntax  to provide a rich description.
update
Type
Any
Required
Description
An object containing the properties and values to be merged with the objects referenced by the
. This field has no effect if the
field is
.
remove
Type
Boolean
Required
Description
If
, the objects referenced by the
are removed from the original document. If
or not provided, the objects are not removed. This field takes precedence over the
field.
x-*
Type
Any
Required
Description
Any number of extension fields can be added to the Action Object that can be used by tooling and vendors.
JSONPath Expression
$.info.title
Description
Selects the
field of the
object.
$.servers[0].url
Description
Selects the
field of the first server in the
array.
Field Name
Type
String
Required

Last updated on