manage-openapi-overlays

| Topic | Guide |

|-------|-------|

| OpenAPI Validation | [content/validation.md](content/validation.md) |

| Security Schemes | [content/security-schemes.md](content/security-schemes.md) |

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

Set SPEAKEASY_API_KEY env var or run speakeasy auth login.

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)

| 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) |

| Output | Description |

|--------|-------------|

| Overlay file | YAML file with JSONPath-targeted changes |

| Modified spec | Transformed OpenAPI spec (when applying) |

Generate an Overlay by Comparing Specs

```bash

speakeasy overlay compare -b -a -o

```

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 -o --out

```

Validate an Overlay

```bash

speakeasy overlay validate -o

```

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

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

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

```

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.

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

```

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.

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

• 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

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