Apply Overlays

What Are Overlays?

The Overlay Specification (opens in a new tab) defines a way to create documents to be merged with an OpenAPI description to update it with additional information.

Overlays are particularly useful in scenarios where the same API specification is used for multiple purposes across different workflows or teams. Instead of making direct changes to the primary spec or needing to manage multiple versions, overlays maintain customizations separately.

These customizations can then be applied to an OpenAPI specification in a new file, ensuring that the API specifications remain flexible and adaptive without altering the core document.

Common Use Cases

Overlays enable a variety of customizations to API specifications. Common scenarios include:

View more examples here.

Creating an Overlay

Create an overlay by creating a new YAML document that details the specific alterations to make to the OpenAPI specification.

With Speakeasy, create overlays manually or automatically.

For a quick generation of differences between two API versions, use the compare command in the Speakeasy CLI.


speakeasy overlay compare --before=./openapi­_original.yaml --after=./openapi.yaml > overlay.yaml

Info Icon

Using compare

The compare feature is designed to assist in identifying differences across OpenAPI documents. However, users requiring precise adjustments may need to manually edit the generated overlay file to suit their needs. You can validate and evaluate your JSONPath expressions here (opens in a new tab).

Anatomy of an Overlay

overlay

Required: Specifies the Overlay Specification version used by the document, currently limited to 1.0.0.

overlay.yaml

overlay: 1.0.0
info:
title: Overlay to fix the Speakeasy bar
version: 0.0.1
actions:
- target: "$.tags"
description: Add a Snacks tag to the global tags list
update:
- name: Snacks
description: All methods related to serving snacks
- target: "$.paths['/dinner']"
description: Remove all paths related to serving dinner
remove: true

info

  • title Required: Describes the overlay's purpose.
  • version Required: Identifies the document's version.
overlay.yaml

overlay: 1.0.0
info:
title: Overlay to fix the Speakeasy bar
version: 0.0.1
actions:
- target: "$.tags"
description: Add a Snacks tag to the global tags list
update:
- name: Snacks
description: All methods related to serving snacks
- target: "$.paths['/dinner']"
description: Remove all paths related to serving dinner
remove: true

actions

Required: An array of ordered actions for the target document, with at least one object per action.

overlay.yaml

overlay: 1.0.0
info:
title: Overlay to fix the Speakeasy bar
version: 0.0.1
actions:
- target: "$.tags"
description: Add a Snacks tag to the global tags list
update:
- name: Snacks
description: All methods related to serving snacks
- target: "$.paths['/dinner']"
description: Remove all paths related to serving dinner
remove: true

target

Required: Specifies a JSONPath query expression to identify the target objects in the target document.

overlay.yaml

overlay: 1.0.0
info:
title: Overlay to fix the Speakeasy bar
version: 0.0.1
actions:
- target: "$.tags"
description: Add a Snacks tag to the global tags list
update:
- name: Snacks
description: All methods related to serving snacks
- target: "$.paths['/dinner']"
description: Remove all paths related to serving dinner
remove: true

description

Optional: Brief explanation of the action being performed. Supports CommonMark syntax for rich text representation.

overlay.yaml

overlay: 1.0.0
info:
title: Overlay to fix the Speakeasy bar
version: 0.0.1
actions:
- target: "$.tags"
description: Add a Snacks tag to the global tags list
update:
- name: Snacks
description: All methods related to serving snacks
- target: "$.paths['/dinner']"
description: Remove all paths related to serving dinner
remove: true

update

Optional: Defines the properties and values to be merged with the objects identified by the target. This property is disregarded if the remove property is set to true.

overlay.yaml

overlay: 1.0.0
info:
title: Overlay to fix the Speakeasy bar
version: 0.0.1
actions:
- target: "$.tags"
description: Add a Snacks tag to the global tags list
update:
- name: Snacks
description: All methods related to serving snacks
- target: "$.paths['/dinner']"
description: Remove all paths related to serving dinner
remove: true

remove

Optional: A boolean value indicating whether the target object should be removed from its map or array. Defaults to false if not specified.

overlay.yaml

overlay: 1.0.0
info:
title: Overlay to fix the Speakeasy bar
version: 0.0.1
actions:
- target: "$.tags"
description: Add a Snacks tag to the global tags list
update:
- name: Snacks
description: All methods related to serving snacks
- target: "$.paths['/dinner']"
description: Remove all paths related to serving dinner
remove: true

overlay

Required: Specifies the Overlay Specification version used by the document, currently limited to 1.0.0.

info

  • title Required: Describes the overlay's purpose.
  • version Required: Identifies the document's version.

actions

Required: An array of ordered actions for the target document, with at least one object per action.

target

Required: Specifies a JSONPath query expression to identify the target objects in the target document.

description

Optional: Brief explanation of the action being performed. Supports CommonMark syntax for rich text representation.

update

Optional: Defines the properties and values to be merged with the objects identified by the target. This property is disregarded if the remove property is set to true.

remove

Optional: A boolean value indicating whether the target object should be removed from its map or array. Defaults to false if not specified.

overlay.yaml

overlay: 1.0.0
info:
title: Overlay to fix the Speakeasy bar
version: 0.0.1
actions:
- target: "$.tags"
description: Add a Snacks tag to the global tags list
update:
- name: Snacks
description: All methods related to serving snacks
- target: "$.paths['/dinner']"
description: Remove all paths related to serving dinner
remove: true

Helpful references: