tomevault-io Validate an OpenAPI Specification
Step 1: Run validation
Call the validate tool on the user's spec:
{"spec": {"file": "<path>"}}
If the user wants strict validation, add "strict": true.
⚠️ Tip for large specs: Use "no_warnings": true for initial triage. Large specs can produce hundreds of warnings that obscure the actual errors. Get the error picture first, then run again without no_warnings to review warnings separately.
Step 2: Report results
If the spec is valid:
- Confirm it passes validation
- Mention the detected OAS version
- Note any warnings (unless
no_warningswas set)
If the spec has errors:
- List each error with its JSON path and a plain-language explanation
- Group related errors (e.g., multiple missing
$reftargets) - Explain why each error matters and what it would cause in practice (tooling failures, code generation issues, etc.)
Paginating large results
Results are paginated (default limit: 100). When returned < error_count, there are more errors:
{"spec": {"file": "<path>"}, "offset": 100, "limit": 100}
⚠️ Strategy for large error sets: Analyze the first page for patterns — if errors are repetitive (e.g., hundreds of missing path parameters), summarize the pattern and total count rather than paging through all of them. Only page further when errors appear diverse or the user needs specifics.
Step 3: Suggest fixes
For each error, explain how to fix it. Common patterns:
| Error type | Suggested fix |
|---|---|
| Missing path parameter | Add the parameter to the operation's parameters array |
| Duplicate operationId | Rename to be unique, following a verb+resource pattern |
Invalid $ref target |
Fix the reference path, or stub the missing schema |
| Missing required field | Add the field with an appropriate value |
If the errors are auto-fixable, offer to run the fix tool:
{"spec": {"file": "<path>"}, "dry_run": true}
Show the user the planned fixes before applying. ✅ When applying, use output to persist:
{"spec": {"file": "<path>"}, "output": "<output-path>"}
⚠️ The fix tool does not modify the input file. Without output, the fixed document is not persisted to disk.
Step 4: Re-validate after fixes
After any changes, ✅ run validate on the output file (not the original input):
{"spec": {"file": "<output-path>"}}
Report the final status.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.