# Create overlays

## What are overlays?

The [Overlay Specification](https://github.com/OAI/Overlay-Specification/tree/3f398c6d38ddb5b4e514bc6a5a5ec487a3293834) defines a way to create overlay documents to be merged with an OpenAPI document to update it with additional information.

Overlays are particularly useful in scenarios where the same OpenAPI document serves multiple purposes across different workflows or teams. Instead of making direct changes to the primary spec or managing multiple versions, overlays maintain customizations separately.

These customizations apply to an OpenAPI document in a new file, ensuring API specifications remain flexible and adaptive without altering the core document.

## Common use cases

Overlays enable various customizations to API specifications. Common scenarios include:

- [Adding Speakeasy extensions](/guides/sdks/overlays/overlays#adding-speakeasy-extensions): Enhance OpenAPI documents with custom Speakeasy extensions for additional functionality or metadata
- [Adding examples to API documentation](/guides/sdks/overlays/overlays#adding-examples-to-api-documentation): Provide clear, concrete examples to clarify API usage
- [Hiding internal APIs from a public SDK](/guides/sdks/overlays/overlays#hiding-internal-apis-from-a-public-sdk): Exclude internal API endpoints from public-facing SDK documentation for security and clarity

[View more examples here](/guides/sdks/overlays/overlays).

## Creating an overlay

Create an overlay by writing a new YAML document that specifies the modifications to the OpenAPI document.

Speakeasy supports both manual and automatic overlay creation.

Generate the differences between two OpenAPI document versions with the `compare` command in the [Speakeasy CLI](/docs/speakeasy-reference/cli/overlay/compare).

```bash
speakeasy overlay compare --before=./openapi_original.yaml --after=./openapi.yaml > overlay.yaml
```

<Callout title="Using compare" type="info">
  The compare feature helps identify differences across OpenAPI documents.
  Precise adjustments may require manual refinement of the generated overlay
  file. Validate and evaluate JSONPath expressions
  [here](https://jsonpath.com/).
</Callout>

## Anatomy of an overlay

### `overlay`

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

```yaml
overlay: 1.0.0
```

### `info`

- `title`: **Required** – Describes the overlay's purpose
- `version`: **Required** – Identifies the document's version

```yaml
overlay: 1.0.0
info:
  title: Overlay to fix the Speakeasy bar
  version: 0.0.1
```

### `actions`

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

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

#### `description`

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

#### `update`

**Optional** – Defines the properties and values to merge 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 to remove the target object from its map or array. Defaults to `false` if not specified.

## Helpful references:

- [Common overlay examples](/guides/sdks/overlays/overlays)
- [Common JSONPath examples](/guides/sdks/overlays/json-path-expressions)

<Callout title="Try Speakeasy's OpenAPI Overlay Playground" type="info">
  For a visual approach to creating or editing overlays, visit{" "}
  <a
    href="https://overlay.speakeasy.com/"
    target="_blank"
    rel="noopener noreferrer"
  >
    overlay.speakeasy.com
  </a>
  .
</Callout>