create-openapi-overlay

Overlays let you customize an OpenAPI spec for SDK generation without modifying the source.

When to Use

• You need to customize SDK output but can't modify the source spec
• Adding x-speakeasy extensions for grouping, naming, or retries
• Fixing lint issues without editing the original file
• User says: "create overlay", "customize SDK", "can't modify spec"

Inputs

Input	Required	Description
Target spec	Yes	Spec to customize
Customizations	Yes	Changes to apply (groups, names, etc.)

Outputs

Output	Description
Overlay file	YAML file with JSONPath-targeted changes

Create Overlay Manually

Create an overlay file with this template structure:

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

Or generate an overlay by comparing two specs:

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

Overlay Capabilities

Overlays are great for:

• Renaming operations (x-speakeasy-name-override)
• Adding descriptions/summaries
• Grouping operations (x-speakeasy-group)
• Adding retry configuration
• Marking endpoints as deprecated
• Adding SDK-specific extensions
• Fixing spec issues without modifying the source
• Adding new endpoints or schemas
• Making portable patches that work across spec versions

Example Overlay

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.users.list(), sdk.users.create(), sdk.users.get(), sdk.users.delete()

JSONPath Targeting

Target	Selects
$.paths['/users'].get	GET /users operation
$.paths['/users/{id}'].*	All operations on /users/{id}
$.components.schemas.User	User schema
$.info	API info object

What NOT to Do

• Do NOT use overlays for invalid YAML/JSON syntax errors
• Do NOT try to deduplicate schemas with overlays (requires structural analysis)
• Do NOT fix broken $ref paths with overlays - fix the source spec instead

Troubleshooting

Error	Cause	Solution
"target not found"	JSONPath doesn't match spec structure	Verify exact path with spec inspection
Changes not applied	Overlay not in workflow	Add overlay to workflow.yaml sources
YAML parse error	Invalid overlay syntax	Check YAML indentation and structure

Related Skills

• apply-openapi-overlay - Apply overlay to spec
• fix-validation-errors-with-overlays - Fix lint errors via overlay
• improve-operation-ids - Improve SDK method naming
• get-ai-suggestions - Generate overlay suggestions automatically