validate-openapi-spec

Use speakeasy lint to check for errors and warnings in your OpenAPI spec.

When to Use

• Checking if a spec is valid before generation
• Identifying errors blocking SDK generation
• User says: "validate spec", "lint spec", "is my spec valid"

Inputs

Input	Required	Description
OpenAPI spec	Yes	Path to spec file (-s)

Outputs

Output	Description
Errors	Issues that block SDK generation
Warnings	Issues that may cause problems
Hints	Best practice suggestions

Command

speakeasy lint openapi --non-interactive -s <path-to-spec>

Output Categories

Severity	Meaning	Action
Error	Blocks SDK generation	Must fix
Warning	May cause issues	Should fix
Hint	Best practice suggestion	Consider fixing

Common Validation Issues

Issue	Solution
Missing operationId	Add operationId or use speakeasy suggest operation-ids
Invalid $ref	Fix the reference path
Missing response schema	Add response schema definitions
Duplicate operationId	Make operation IDs unique

AI-Friendly Output

For commands with large outputs, pipe to grep or tail to reduce context:

speakeasy lint openapi --non-interactive -s ./openapi.yaml 2>&1 | grep -E "(error|warning)"

What NOT to Do

• Do NOT fix errors one-by-one without understanding root cause
• Do NOT ignore warnings - they often indicate real problems
• Do NOT modify the source spec without asking if it's externally managed

Troubleshooting

Error	Cause	Solution
"file not found"	Invalid spec path	Check the file path exists
Many duplicate errors	Shared schema issues	Fix the root schema, not each reference
"$ref not found"	Broken reference	Check the reference path matches actual location

Related Skills

• diagnose-generation-failure - When lint errors cause generation to fail
• fix-validation-errors-with-overlays - Fix issues without modifying source spec
• get-ai-suggestions - Get AI-powered suggestions for improvements