Last updated:
OpenAPI Validator
This OpenAPI validator checks Swagger and OpenAPI specs against the official schemas.
Checked in your browser as you type. A file you open is read here and never uploaded.
How to use the OpenAPI validator
Paste a spec into the editor, open a YAML or JSON file, or load one of the samples. The validator reads the swagger or openapi field to tell the version, checks the document against the official JSON Schema for that version, then runs the checks a schema can't express. The results list every problem with its line and column, where it is in the document, and how to fix it; the line numbers in the editor's margin turn red for errors and amber for warnings, and the line link moves the cursor to the problem. It checks again as you type.
The samples are a small pet store written three times, as Swagger 2.0, OpenAPI 3.0 and OpenAPI 3.1, all valid, and a broken 3.0 spec with ten mistakes taken from the list below. "Copy a share link" makes a link that opens the same spec, and "Open in the OpenAPI Editor" moves it to the editor, with its live documentation preview. A spec over 1 MB, such as a large public API's, isn't shown in the editor, but it's checked in full, and each problem still gives its line in the file.
The second tab, "Validate a response", checks a real response against the spec: choose the operation, type the status code and paste the body, and optionally the response headers. Switch it to "A request" to check a request body, its query string and its headers against the operation's request body and parameters. It uses the spec from the first tab, so fix the spec's errors first.
What the official schemas check, and what they don't
The OpenAPI Initiative publishes a JSON Schema for each version of the specification at spec.openapis.org. Swagger 2.0 and OpenAPI 3.0 are described in JSON Schema Draft 4, 3.1 and 3.2 in Draft 2020-12, and the validator runs each with Ajv, using the right draft for each. The schemas catch the structural mistakes: a missing info or paths, a response without a description, a field in the wrong place or misspelled (only fields starting with x- may be added), a value of the wrong type, and a parameter that is neither a query, header, path or cookie parameter.
What a JSON Schema can't do is compare one part of the document with another. So the validator also checks that every internal $ref points to something, that each {name} in a path has a path parameter and each path parameter appears in its path, that no parameter, operationId or templated path is listed twice, that every security scheme a requirement names is defined, and that server URLs are URLs whose variables are defined. In OpenAPI 3.1 and 3.2, where an operation may legally have no responses, it warns when one has none, and it warns about components that nothing refers to.
In 3.1 and 3.2, the official schema accepts any object as a Schema Object, because those are full JSON Schema. The validator checks each one against the JSON Schema 2020-12 meta-schema, so type: strin or a negative minLength is reported there too. Ajv's error output for OpenAPI 3.0 is noisy, because the schema offers alternatives such as "a Response or a $ref" for most fields; the validator works out which alternative you meant and reports only its errors.
It doesn't lint style: missing summaries, operationId naming, or whether every operation documents its error responses are linter rules, not validity. The CI tools below cover them.
Swagger 2.0 vs OpenAPI 3.0 vs 3.1
| Swagger 2.0 | OpenAPI 3.0 | OpenAPI 3.1 and 3.2 | |
|---|---|---|---|
| First line | swagger: "2.0" | openapi: 3.0.3 | openapi: 3.1.1 |
| Servers | host, basePath, schemes | servers, with variables | servers, with variables |
| Request body | a parameter with in: body | requestBody, by media type | requestBody, by media type |
| Reusable parts | definitions, parameters, responses | components | components, plus pathItems |
| Schemas | a subset of JSON Schema Draft 4 | an extended subset of Draft 4/5 | JSON Schema 2020-12 |
| Null | not expressible | nullable: true | type: [string, "null"] |
| Webhooks | no | no (callbacks only) | yes, top-level webhooks |
The step from 2.0 to 3.0 reorganised the document; the step from 3.0 to 3.1 mostly changed schemas. 3.2, published in September 2025, adds to 3.1 (a query method among others) without breaking it. A spec doesn't become 3.1 by changing its first line: nullable stops working, and boolean exclusiveMinimum must become a number. The validator checks a spec against the version it declares, so after an upgrade the schema errors show what still needs converting.
The 10 most common spec errors and how to fix them
- A response without a description. Every Response Object needs a description, even when the response has no body. It's the most common error the official schema reports.
responses: "204": {}responses: "204": description: Deleted - A $ref that points nowhere. The schema can only check that a $ref is a string. The validator follows every internal reference and suggests the nearest existing name when it's a typo.
$ref: "#/components/schemas/Pets"$ref: "#/components/schemas/Pet" - A path parameter that isn't declared. Each {name} in a path needs a parameter with in: path, on the path or on every operation under it.
/pets/{petId}: get: responses: .../pets/{petId}: parameters: - name: petId in: path required: true schema: type: integer - A path parameter without required: true. Path parameters are always required, and the spec makes you say so.
- name: petId in: path schema: type: integer- name: petId in: path required: true schema: type: integer - A version written as a number. YAML reads an unquoted 1.0 as the number 1, and info.version must be a string. The same goes for openapi: 3.0 written without its patch number.
info: version: 1.0info: version: "1.0" - OpenAPI 3.1 syntax in a 3.0 spec. 3.0's Schema Object takes one type and doesn't know const, examples or $defs. Either write 3.0 syntax, or change the openapi field to 3.1.0.
openapi: 3.0.3 ... type: [string, "null"]openapi: 3.0.3 ... type: string nullable: true - A parameter without in. Without in, a parameter has no location; a parameter is identified by its name and location together.
- name: limit schema: type: integer- name: limit in: query schema: type: integer - The same operationId twice. operationIds must be unique: code generators use them as function names, and the second one overwrites the first.
/pets: get: operationId: getPet /pets/{petId}: get: operationId: getPet/pets: get: operationId: listPets /pets/{petId}: get: operationId: getPet - A security scheme used but never defined. Each name in a security requirement must match a scheme under components.securitySchemes (securityDefinitions in Swagger 2.0).
security: - apiKey: []components: securitySchemes: apiKey: type: apiKey in: header name: X-API-Key - A server URL without a scheme. Without https://, a host and port read as a relative path. Use a full URL, or a path like /v1 relative to where the spec is served.
servers: - url: api.example.com:8080/v1servers: - url: https://api.example.com:8080/v1
The broken sample spec has all ten but the fourth, plus a component no $ref uses: load it to see how each is reported.
Validating responses against the spec
A valid spec can still describe an API that behaves differently. Paste a real response into the second tab to see whether it matches: a field the schema requires that the API leaves out, a number sent as a string, or an enum value the spec doesn't list are reported as JSON pointers into the body, such as /items/0/status, with a suggested fix. The sample response, a pet whose id is a string and whose status is "adopted", shows three of them. Requests work the same way, and a property marked readOnly in a request body is flagged as one the client shouldn't send.
How to validate in CI
A browser tool is for finding and fixing problems; your build should catch them before they ship. Two open-source command-line tools validate a spec and lint it against style rules, and both exit with an error code when the spec has errors, which fails the build:
- Spectral (Stoplight) needs a ruleset; the built-in OpenAPI one checks Swagger 2.0 and OpenAPI 3 documents. Its
--format github-actionsoption annotates the problems on the pull request. - The Redocly CLI lints with its recommended rules by default, and its bundle command joins a spec split over several files into one.
# .spectral.yaml
extends: ["spectral:oas"] npx @stoplight/spectral-cli lint openapi.yaml
npx @redocly/cli lint openapi.yaml When a spec changes, the Breaking Change Detector compares the old and new versions and lists the changes that would break clients, and the API versioning guide covers what to do about them.
FAQ
Which versions does the validator check?
Swagger 2.0, and OpenAPI 3.0, 3.1 and 3.2, in YAML or JSON. It reads the swagger or openapi field and uses the official JSON Schema for that version, published at spec.openapis.org: Swagger 2.0 (2017-08-27), OpenAPI 3.0 (2024-10-18), OpenAPI 3.1 (2026-08-03), OpenAPI 3.2 (2026-08-30).
Is my spec uploaded anywhere?
No. The spec is parsed and checked in your browser (in a background thread where the browser allows one), and a file you open is read there too. The validator records what kind of check ran: the spec's version, its counts of paths and operations, the numbers of errors and warnings, and the codes of the problems found, never the spec, its paths, titles or server addresses, or a response body. See the privacy policy.
Why does a spec that passes the official schema still show errors?
The JSON Schemas check the shape of the document, not its meaning. They can't tell that a $ref points to nothing, that {petId} in a path has no matching parameter, that two operations share an operationId, or that a security requirement names a scheme nobody defined. Those come from the validator's own checks, marked "spec rule" in the results.
Does it follow external $refs?
No. A $ref to another file or a URL is reported once per file as a note, and its target isn't fetched or checked. To check a spec split over several files, bundle it into one first, for example with the Redocly CLI's bundle command.
How does response validation work?
Pick an operation and a status code, paste the body, and the validator finds the matching response (the exact code, then a range such as 4XX, then default) and checks the body against its schema. OpenAPI 3.0 and Swagger 2.0 schemas are converted to JSON Schema first: nullable allows null, readOnly properties aren't expected in a request and writeOnly ones in a response, and discriminator is noted but not used, since oneOf and anyOf decide. Response headers and a request's query string and headers are checked too.
Can I share a spec with someone?
"Copy a share link" puts the spec, compressed, after the # in the page's address. Browsers don't send that part to a server, so the link works without anything being stored, but anyone who has it can read the spec. Specs too large for an address can't be shared this way.
Related tools
- OpenAPI Editor: write a spec with a live documentation preview; it runs this validator as you type.
- JSON Schema Validator: check JSON against a schema lifted out of a spec, in any draft from 4 to 2020-12.
- Mock Data Generator: make fake records from a spec's component schemas, to test a client against.
- YAML to JSON converter: see which values in a YAML spec would change type, such as an unquoted version.
- Breaking Change Detector: compare two versions of a spec before you release.