manage-openapi-overlays

Overlays let you customize an OpenAPI spec for SDK generation without modifying the source. This skill covers creating overlay files, applying them to specs, and using them to fix validation errors.

Content Guides

Topic	Guide
OpenAPI Validation	content/validation.md
Security Schemes	content/security-schemes.md

These guides cover validating specs, fixing common issues, and configuring authentication methods.

Authentication

Set

SPEAKEASY_API_KEY

env var or run

speakeasy auth login

When to Use

Use this skill when you need to manually work with overlay files:

Creating an overlay file from scratch with specific JSONPath targets
Applying an existing overlay file to a spec
Validating overlay syntax and structure
Comparing two specs to generate an overlay
Understanding overlay mechanics (actions, targets, update/remove)
Fixing lint issues via manual overlay creation
User says: "create overlay", "apply overlay", "overlay file", "manual overlay", "overlay syntax", "JSONPath targeting", "validate overlay"

NOT for: AI-powered naming suggestions (see

improve-sdk-naming

instead)

Inputs

Input	Required	Description
Target spec	Yes	OpenAPI spec to customize or fix
Customizations	Depends	Changes to apply (groups, names, retries, descriptions)
Overlay file	Depends	Existing overlay to apply (for apply workflow)
Lint output	Helpful	Validation errors to fix (for fix workflow)

Outputs

Output	Description
Overlay file	YAML file with JSONPath-targeted changes
Modified spec	Transformed OpenAPI spec (when applying)

Commands

Generate an Overlay by Comparing Specs

bash

speakeasy overlay compare -b <before-spec> -a <after-spec> -o <output-overlay>

Use this when you have a modified version of a spec and want to capture the differences as a reusable overlay.

Apply an Overlay to a Spec

bash

speakeasy overlay apply -s <spec-path> -o <overlay-path> --out <output-path>

Validate an Overlay

bash

speakeasy overlay validate -o <overlay-path>

Creating an Overlay Manually

Create an overlay file with this structure:

yaml

overlay: 1.0.0
info:
  title: My Overlay
  version: 1.0.0
actions:
  - target: "$.paths['/example'].get"
    update:
      x-speakeasy-group: example
      x-speakeasy-name-override: getExample

Each action has a

target

(JSONPath expression) and an

update

(object to merge) or

remove

(boolean to delete the target).

Example: SDK Method Naming and Grouping

yaml

overlay: 1.0.0
info:
  title: SDK Customizations
  version: 1.0.0
actions:
  - target: "$.paths['/users'].get"
    update:
      x-speakeasy-group: users
      x-speakeasy-name-override: list
  - target: "$.paths['/users'].post"
    update:
      x-speakeasy-group: users
      x-speakeasy-name-override: create
  - target: "$.paths['/users/{id}'].get"
    update:
      x-speakeasy-group: users
      x-speakeasy-name-override: get
  - target: "$.paths['/users/{id}'].delete"
    update:
      x-speakeasy-group: users
      x-speakeasy-name-override: delete
      deprecated: true

This produces SDK methods:

sdk.users.list()

sdk.users.create()

sdk.users.get()

sdk.users.delete()

Example: Apply Overlay

bash

# Apply overlay and write merged spec
speakeasy overlay apply -s openapi.yaml -o sdk-overlay.yaml --out openapi-modified.yaml

# Compare two specs to generate an overlay
speakeasy overlay compare -b original.yaml -a modified.yaml -o changes-overlay.yaml

Using in Workflow (Recommended)

Instead of applying overlays manually, add them to

.speakeasy/workflow.yaml

yaml

sources:
  my-api:
    inputs:
      - location: ./openapi.yaml
    overlays:
      - location: ./naming-overlay.yaml
      - location: ./grouping-overlay.yaml

Overlays are applied in order. Later overlays can override earlier ones. This approach ensures overlays are always applied during

speakeasy run

Common Fix Patterns

Use overlays to fix validation issues when you cannot edit the source spec.

Issue	Overlay Fix
Poor operation names	Add `x-speakeasy-name-override` to the operation
Missing descriptions	Add `summary` or `description` to the operation
Missing tags	Add `tags` array to the operation
Need operation grouping	Add `x-speakeasy-group` to operations
Need retry config	Add `x-speakeasy-retries` to operations or globally
Deprecate an endpoint	Add `deprecated: true` to the operation
Add SDK-specific metadata	Add any `x-speakeasy-*` extension

Fix Workflow

bash

# 1. Validate the spec to identify issues
speakeasy lint openapi --non-interactive -s openapi.yaml

# 2. Create an overlay file targeting each issue (see patterns above)

# 3. Add overlay to workflow.yaml under sources.overlays

# 4. Regenerate the SDK
speakeasy run --output console

Speakeasy Extensions Reference

Extensions (

x-speakeasy-*

) customize SDK generation. Apply them via overlays.

Extension	Applies To	Purpose
`x-speakeasy-retries`	Operation or root	Configure retry behavior
`x-speakeasy-pagination`	Operation	Enable automatic pagination
`x-speakeasy-name-override`	Operation	Override SDK method name
`x-speakeasy-group`	Operation	Group methods under namespace
`x-speakeasy-unknown-values`	Schema with enum	Allow unknown enum values
`x-speakeasy-globals`	Root	Define SDK-wide parameters
`x-speakeasy-custom-security-scheme`	Security scheme	Multi-part custom auth

Retries

yaml

actions:
  - target: "$.paths['/resources'].get"  # Or "$" for global
    update:
      x-speakeasy-retries:
        strategy: backoff
        backoff:
          initialInterval: 500      # ms
          maxInterval: 60000        # ms
          maxElapsedTime: 3600000   # ms
          exponent: 1.5
        statusCodes: ["5XX", "429"]
        retryConnectionErrors: true

Pagination

Offset/Limit:

yaml

actions:
  - target: "$.paths['/users'].get"
    update:
      x-speakeasy-pagination:
        type: offsetLimit
        inputs:
          - name: offset
            in: parameters
            type: offset
          - name: limit
            in: parameters
            type: limit
        outputs:
          results: $.data
          numPages: $.meta.total_pages

Cursor:

yaml

actions:
  - target: "$.paths['/events'].get"
    update:
      x-speakeasy-pagination:
        type: cursor
        inputs:
          - name: cursor
            in: parameters
            type: cursor
        outputs:
          results: $.events
          nextCursor: $.next_cursor

Open Enums (Anti-Fragility)

Prevent SDK breakage when APIs return new enum values:

yaml

actions:
  - target: "$.components.schemas.Status"
    update:
      x-speakeasy-unknown-values: allow

For all enums (add

x-speakeasy-jsonpath: rfc9535

at overlay root):

yaml

actions:
  - target: $..[?length(@.enum) > 1]
    update:
      x-speakeasy-unknown-values: allow

Global Headers

Add SDK-wide headers as constructor options:

yaml

actions:
  - target: $
    update:
      x-speakeasy-globals:
        parameters:
          - $ref: "#/components/parameters/TenantId"
  - target: $.components
    update:
      parameters:
        TenantId:
          name: X-Tenant-Id
          in: header
          schema:
            type: string

Result:

client = SDK(api_key="...", tenant_id="tenant-123")

Custom Security Schemes

For complex auth (HMAC, multi-part credentials):

yaml

actions:
  - target: $.components
    update:
      securitySchemes:
        hmacAuth:
          type: http
          scheme: custom
          x-speakeasy-custom-security-scheme:
            schema:
              type: object
              properties:
                keyId:
                  type: string
                keySecret:
                  type: string
  - target: $
    update:
      security:
        - hmacAuth: []

With

envVarPrefix: MYAPI

in gen.yaml, generates env var support for

MYAPI_KEY_ID

MYAPI_KEY_SECRET

JSONPath Targeting Reference

Target	Selects
`$.paths['/users'].get`	GET /users operation
`$.paths['/users/{id}'].*`	All operations on /users/{id}
`$.paths['/users'].get.parameters[0]`	First parameter of GET /users
`$.components.schemas.User`	User schema definition
`$.components.schemas.User.properties.name`	Name property of User schema
`$.info`	API info object
`$.info.title`	API title
`$.servers[0]`	First server entry

What NOT to Do

Do NOT use overlays for invalid YAML/JSON syntax errors -- fix the source file
Do NOT try to fix broken
```
$ref
```
paths with overlays -- fix the source spec
Do NOT use overlays to fix wrong data types -- this is an API design issue
Do NOT try to deduplicate schemas with overlays -- requires structural analysis
Do NOT ignore errors that require source spec fixes -- overlays cannot solve everything
Do NOT modify source OpenAPI specs directly if they are externally managed
Do NOT use a
```
speakeasy overlay create
```
command -- it does not exist

Troubleshooting

Error	Cause	Solution
"target not found"	JSONPath does not match spec structure	Verify exact path and casing by inspecting the spec
Changes not applied	Overlay not in workflow	Add overlay to `sources.overlays` in `workflow.yaml`
"invalid overlay"	Malformed YAML	Check overlay structure: needs `overlay` , `info` , `actions`
YAML parse error	Invalid overlay syntax	Check YAML indentation and quoting
No changes visible	Wrong target path	Use `$.paths['/exact-path']` with exact casing
Errors persist after overlay	Issue not overlay-appropriate	Check if the issue requires a source spec fix instead
Overlay order conflict	Later overlay overrides earlier	Reorder overlays in `workflow.yaml` or merge into one file

manage-openapi-overlays

NPX Install

Tags

SKILL.md Content

manage-openapi-overlays

Content Guides

Authentication

When to Use

Inputs

Outputs

Commands

Generate an Overlay by Comparing Specs

Apply an Overlay to a Spec

Validate an Overlay

Creating an Overlay Manually

Example: SDK Method Naming and Grouping

Example: Apply Overlay

Using in Workflow (Recommended)

Common Fix Patterns

Fix Workflow

Speakeasy Extensions Reference

Retries

Pagination

Open Enums (Anti-Fragility)

Global Headers

Custom Security Schemes

JSONPath Targeting Reference

What NOT to Do

Troubleshooting