OpenAPI Validator
Validate OpenAPI 3.0/3.1/3.2 and Swagger 2.0 YAML or JSON with line numbers: official schemas, $ref across files, path params, examples. Nothing is uploaded.
- Runs in your browser
- Tool input is not uploaded to ZeroTool servers
- Free · No Sign-Up
Scan with WeChat to share this tool
Examples, details and FAQ Worked examples, how it compares with other tools, and answers to common questions.
Paste an OpenAPI or Swagger document, open the files, or drop a folder. The validator checks it against the official JSON Schema for its version, follows $ref between files, and adds the rules that the schemas cannot express. Every problem shows the line and column; click it to select that line in the editor.
Example: a 3.1 description with four problems
This is the built-in example. The version field is an unquoted date, which YAML 1.2 reads as a string, so it is not reported.
openapi: 3.1.0
info:
title: Orders API
version: 2026-10-02
security:
- bearerAuth: []
paths:
/orders/{orderId}:
get:
operationId: getOrder
responses:
"200":
description: One order
content:
application/json:
schema:
$ref: "#/components/schemas/Order"
example:
id: 42
total: "19.90"
components:
schemas:
Order:
type: object
required: [id, total]
properties:
id: {type: integer}
total: {type: number}
securitySchemes:
bearer:
type: http
scheme: bearer
6:5 Error Security scheme "bearerAuth" is not declared in components.securitySchemes.
9:5 Error GET /orders/{orderId}: path parameter "orderId" is not declared. Add a parameter with in: path and name: orderId.
20:17 Warning Example does not match the schema at /total: Must be number.
30:5 Warning Security scheme "bearer" is not referenced anywhere.
The official 3.1 schema accepts this document: a security requirement is a map of names, and the schema does not compare those names with components.securitySchemes. The two errors come from the extra rules below.
What is checked
| Check | Level | Source |
|---|---|---|
| Structure: required and unknown fields, types, parameter and response shapes | Error | Official JSON Schema for the version |
Schema Objects in 3.1 / 3.2 (for example required: true on a property, type: int) | Error | JSON Schema 2020-12 meta-schema, which 3.1 adopts |
Every local $ref points to something, in this file or another added file | Error | Reference Object |
Each {name} in a path has an in: path parameter, and the other way round | Error | Parameter Object |
| Paths that differ only in parameter names | Error | Paths Object |
Duplicate parameters (same name and in), duplicate operationId, duplicate tag names | Error | Operation, Path Item and OpenAPI Objects |
| Security requirements name a declared scheme | Error | Security Requirement Object |
| Server variable default inside its enum | Error in 3.1+, warning in 3.0 (MUST vs SHOULD) | Server Variable Object |
Boolean exclusiveMinimum / exclusiveMaximum without minimum / maximum in the same object (Schema, and in 2.0 also non-body Parameter, Header and Items Objects) | Error in 2.0, warning in 3.0 | 2.0 uses JSON Schema draft 4 (§5.1.2.1 and §5.1.3.1: the limit MUST also be present); 3.0 uses Wright draft 00, which drops that MUST, so the keyword just has no effect. The official schemas, Redocly CLI 2.57.0 and Spectral 6.17.0 do not check this on its own. |
| Examples match their schema (readOnly is not required in requests, writeOnly not in responses) | Warning | SHOULD in Parameter and Media Type Objects |
Unused components, undefined or unused server variables, query strings in path keys, nullable in 3.1 | Warning | Common mistakes that the linters below also report |
Example: two paths that are the same template
GitHub publishes its REST API description as api.github.com.yaml (9.9 MB, main branch on 2026-10-02). The validator finds 2 errors in it: two pairs of attestation paths that differ only by the parameter name. Redocly CLI 2.57.0 and Spectral 6.17.0 report the same two pairs. This excerpt reproduces one:
openapi: 3.0.3
info:
title: Attestations (excerpt)
version: 1.1.4
paths:
/orgs/{org}/attestations/{attestation_id}:
delete:
parameters:
- {name: org, in: path, required: true, schema: {type: string}}
- {name: attestation_id, in: path, required: true, schema: {type: integer}}
responses:
"204": {description: Deleted}
/orgs/{org}/attestations/{subject_digest}:
get:
parameters:
- {name: org, in: path, required: true, schema: {type: string}}
- {name: subject_digest, in: path, required: true, schema: {type: string}}
responses:
"200": {description: OK}
13:3 Error Path "/orgs/{org}/attestations/{subject_digest}" is the same template as "/orgs/{org}/attestations/{attestation_id}" (only the parameter names differ). The specification does not allow both.
A router cannot tell /orgs/acme/attestations/42 apart for these two paths. On the full file the tool also lists 187 examples that do not match their schema and 7 unused schemas. It took 2.7 seconds in Node.js 24 on an Apple M1 Max; the page runs the same code in a Web Worker, so the page stays usable.
Swagger 2.0 and YAML details
Swagger 2.0 documents are checked against the Swagger 2.0 schema with the same reference, path parameter, security and example rules. A note suggests converting with swagger2openapi if you want OpenAPI 3.
swagger: "2.0"
info:
title: Pets
version: "1.0"
paths:
/pets/{petId}:
get:
parameters:
- {name: id, in: path, required: true, type: integer}
responses:
"200":
description: OK
schema:
$ref: "#/definitions/Pett"
definitions:
Pet:
type: object
1:1 Note Swagger 2.0 document, checked against the Swagger 2.0 schema. To move to OpenAPI 3, convert it (for example: npx swagger2openapi swagger.yaml -o openapi.yaml) and validate the result.
7:5 Error GET /pets/{petId}: path parameter "petId" is not declared. Add a parameter with in: path and name: petId.
7:5 Error GET /pets/{petId}: parameter "id" has in: path, but the path has no {id}.
14:13 Error Reference "#/definitions/Pett" does not point to anything in this document.
16:3 Warning Definition "Pet" is not referenced anywhere.
YAML is read with the YAML 1.2 core schema, plus merge keys (<<: *anchor). A key that appears twice in one mapping is a syntax error with its line, in JSON input too. Integers larger than 253, such as maximum: 9223372036854775807, get a note because JavaScript reads them as approximate values.
How it compares
We ran the same test file through other validators on 2026-10-02. It had four errors (an undeclared path parameter, an undeclared security scheme, two equivalent paths, required: true on a property) and an unquoted date in info.version.
- Redocly CLI 2.57.0 and Spectral 6.17.0 (
spectral:oas) found all four. They also apply style rules (summaries, 4XX responses, license, servers), and both flag example strings for XML media types; this tool treats a string example of a non-JSON media type as the serialized form and does not compare it with the schema. On the 9.9 MB GitHub description Spectral took 32 s and Redocly 5 s. - swagger-parser 13.1.0 reported the document as valid.
- Swagger Editor 5.8.9 (editor.swagger.io) checks in the browser and found the path parameter and the
requiredproblem, not the equivalent paths or the undeclared scheme. - ApiNotes (apinotes.io, first Bing result for "openapi validator") sent the document to
api.apinotes.ioand reportedinfo.version"must be string", a false error caused by reading the date as a timestamp. - APIMatic validates through its VS Code extension, which needs an APIMatic account and an internet connection (its documentation), so we did not test it.
Limits
- No style rules. For naming, descriptions or a team ruleset, run Redocly CLI or Spectral after this check.
- URLs in
$refare not fetched, so they are listed as notes and not checked. If a referenced file is missing, add the file instead. Anchor references (#name) are not checked. - Example checks stop after 4 seconds on very large descriptions, with a note. Each example reports its first mismatch and a count of the rest.
- Inputs over 2,097,152 characters are checked when you click Validate; files over 50 MiB in total are not loaded.
- An opened file larger than 512 K characters is validated in full but shown as a read-only window of up to 300 lines and 49,152 characters, because putting about 10 MB into the editor stalls the page for about half a second. Clicking a line number moves the window to that line. Copy full text, Download and Edit full text (slow) give access to the whole file. Pasting that much text into the editor yourself still stalls the page.
- YAML is read with js-yaml 4.3.2, which stops a document nested more than 100 levels deep, whose merge keys handle more than 10,000 mappings and keys in total, or that lists more than 100 mappings in one merge key. The error names the limit and its line.
Related tools: generate types with OpenAPI to TypeScript, check a payload against a schema with the JSON Schema Validator, or find YAML syntax errors with the YAML Validator.
FAQ
Which versions does the validator support?
Swagger 2.0 and OpenAPI 3.0, 3.1 and 3.2. The tool reads the swagger or openapi field and checks the document against the official JSON Schema for that version: the Swagger 2.0 schema from the OpenAPI Initiative repository and the 3.0 (2024-10-18), 3.1 (2026-08-03) and 3.2 (2026-08-30) schemas from spec.openapis.org.
Is my API description uploaded?
No. Parsing and all checks run in your browser: in a Web Worker, or on the page itself if a Worker cannot start. The document is not uploaded or saved in browser storage. External $ref URLs are not fetched; files you add under Other files are read for validation without uploading them. After a committed text or file edit, file action, Example or Validate, a completed check records only the tool name and validate_success or validate_error, according to whether validation found errors. Typing still updates results but does not record usage. Restoring or initially rendering the page, unchanged validation results, worker failures and obsolete replies do not add an event. Document content is not included.
My spec uses $ref to other files. Can it check them?
Yes. Open several files or a whole folder, or add files by hand under Other files and name each one by the path its $ref uses (for example schemas/pet.yaml). References are resolved across the files, and problems are reported in the file where the text is. References to URLs and to files you did not add are listed as notes.
What is the difference between an error and a warning?
Errors break a MUST in the specification or the official schema, so other tools may reject the document. Warnings are SHOULD rules and likely mistakes: examples that do not match their schema, unused components, server variables that are not defined. Notes list what was not checked and values to keep in mind.
Why does version: 2024-01-15 pass here but fail in some validators?
The validator reads YAML with the YAML 1.2 core schema, as Redocly CLI, Spectral and swagger-parser do, so an unquoted date is a string. Parsers that use YAML 1.1 timestamps turn it into a date, and the schema then rejects info.version. Quote the value ("2024-01-15") so every parser reads a string.
Can it check GitHub's REST API description?
Yes. Open api.github.com.yaml from github/rest-api-description (9.9 MB on the main branch on 2026-10-02). The tool reports 2 errors, two pairs of attestation paths that differ only by the parameter name (Redocly CLI 2.57.0 and Spectral 6.17.0 report the same pairs), plus 187 examples that do not match their schema and 7 unused schemas. A file this large is validated in full but shown in a read-only window of up to 300 lines and 49,152 characters.