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 failfix-validation-errors-with-overlays - Fix issues without modifying source specget-ai-suggestions - Get AI-powered suggestions for improvements
