How to validate an OpenAPI spec
- 1
Paste, upload or load it. Paste YAML or JSON into the editor, drop a file on it, or load it from a URL (GitHub links work).
- 2
Read the result. It validates as you type. Each issue says what's wrong and how to fix it, and whether it's an error or just a warning.
- 3
Jump to the line. Click an issue to select its line in the editor. Lines with problems are marked in the gutter.
- 4
Fix and repeat. The list updates as you edit, until it says Valid.
What it checks
First, the official JSON Schema for the document's version: required fields, allowed values, types and unknown fields. Raw schema errors are famously unreadable (one mistake can produce a dozen oneOf failures), so they're boiled down to the one that matters. Then the rules the schema can't express:
- References: every local
$refresolves. - Path parameters: each
{param}in a path is defined within: pathandrequired: true, and no path parameter is missing from its path. - Uniqueness: no duplicate operationIds, no parameter listed twice, and no two paths that differ only in parameter names (
/pets/{id}and/pets/{petId}). - Security: every security requirement names a scheme that's defined.
- Servers: every
{variable}in a server URL is defined, and defaults are in their enums.
Warnings make it a lightweight OpenAPI linter too. They flag things that are allowed but usually mistakes: operations without an operationId, schemas nothing references, fields next to a $ref that 3.0 ignores, and 3.0 habits such as nullable in a 3.1 document.
Common OpenAPI errors and how to fix them
{name} in a path needs a parameter with that exact name, in: path and required: true, either on the operation or on the path item. A renamed placeholder ({id} in the path, petId in the parameter) is the usual cause.description is required on every response, even a 204. It's the most common schema error in hand-written specs.#/components/schemas/Pet, or a schema that was renamed. The validator resolves every local reference and suggests the closest name that does exist.version: 1.0 is the number 1 in YAML. Quote it: version: "1.0".sumary or operationID is an error. You get a “did you mean”; custom fields must start with x-.OpenAPI 3.0 vs 3.1: what changes for validation
3.1 adopted full JSON Schema, so a few 3.0 habits are errors or no-ops in 3.1. The validator picks the right rules from the openapi field and warns when 3.0 syntax shows up in a 3.1 document.
| OpenAPI 3.0 | OpenAPI 3.1 | |
|---|---|---|
| Nullable | nullable: true | type: ["string", "null"] |
| Exclusive limits | exclusiveMinimum: true + minimum | exclusiveMinimum: 5 |
| Examples in schemas | example: … | examples: [ … ] |
| Webhooks | not supported | top-level webhooks |
| Schema dialect | OpenAPI's subset of JSON Schema | JSON Schema 2020-12 |
| paths | required | optional (paths, components or webhooks) |
OpenAPI to MCP: validate the spec first
A common way to give an AI agent access to an API is to generate an MCP (Model Context Protocol) server from its OpenAPI spec: each operation becomes a tool, the operationId becomes its name, the summary and description become what the model reads, and the parameters and request body become its input schema. That makes the spec's quality the agent's quality:
- Broken references and missing path parameters give tools input schemas that can't be called correctly, or make the generator skip the operation.
- Missing or duplicate operationIds leave tools with invented or colliding names the model can't tell apart.
- Missing summaries leave the model guessing what a tool does.
Validate the spec here first, fix what it finds, then generate the MCP server.
A Swagger validator, too
Swagger 2.0 is still everywhere. Paste a swagger: "2.0" document and it's checked against the Swagger 2.0 schema, with the same reference, parameter and operationId checks. Use To JSON / To YAML to switch formats either way.
Questions
Is this OpenAPI validator free?
Yes. No account, no sign-up and no limits on how often you validate. Paste a spec and it's checked as you type.
Is my API spec uploaded anywhere?
No. Parsing and validation run in your browser, in a Web Worker, so what you paste or upload never leaves your machine. The one exception is Load from URL: our server downloads that URL for you (browsers block most cross-site downloads) and passes it straight back without storing it.
Which versions does it support?
OpenAPI 3.2, 3.1 and 3.0, and Swagger 2.0, in YAML or JSON. The version is read from the openapi (or swagger) field, and the document is checked against the official JSON Schema for that version.
Can it validate a Swagger 2.0 file?
Yes. It works as a Swagger validator too: Swagger 2.0 documents are checked against the Swagger 2.0 schema, with the same reference, path parameter and operationId checks as OpenAPI 3.
What's the difference between this and the JSON Schema check alone?
The official schema can't catch everything. On top of it, this tool resolves every local $ref, checks that each {parameter} in a path is defined with in: path and required: true, finds duplicate operationIds and duplicate or equivalent paths, checks that security requirements name a defined scheme, and checks server URL variables.
Why does it say my version must be a string?
In YAML, version: 1.0 (without quotes) is the number 1, not the text 1.0, and OpenAPI requires a string. Quote it: version: "1.0". The same goes for openapi: 3.1 without a patch number.
Does it resolve external $refs to other files?
Not yet. References inside the document (#/components/…) are resolved and checked; references to other files or URLs are listed as a warning so you know they weren't checked. Bundle a multi-file spec into one file first to validate all of it.
Should I validate an OpenAPI spec before converting it to an MCP server?
Yes, and it's worth doing. OpenAPI-to-MCP generators build one tool per operation, so a broken $ref, a missing path parameter or a duplicate operationId becomes a broken or missing tool. See the MCP section above.