OpenAPI Validator

Validate an OpenAPI 3.0 or 3.1 document and get every structural error located by JSON Pointer, with unresolved references reported rather than skipped.

Specification

YAML

Petstore

OpenAPI 3.0.3 · v1.0.0

2 errors, 1 warning

Paths: 2
Operations: 2
Schemas: 1
Servers: 0
Tags: 0
Security schemes: 0

Issues

3 shown

Warnings

warningGET /pets/{petId} has no operationId.
Code generators fall back to a name derived from the path, which changes whenever the path does.
/paths/~1pets~1{petId}/get
errorPath "/pets/{petId}" uses {petId} but no parameter declares it.
Add a parameter with in: path, name: petId and required: true.
/paths/~1pets~1{petId}/get
error"#/components/schemas/NewPet" does not resolve.
The target does not exist in this document.
/paths/~1pets/post/requestBody/content/application~1json/schema/$ref

Operations

get/pets/{petId}no id

post/petscreatePet

Parsed and validated in your browser — an unpublished specification is never uploaded. External $ref targets are not fetched, and are reported as unchecked rather than passed over.

About the OpenAPI Validator

Paste an OpenAPI 3.0 or 3.1 document, in YAML or JSON, and this OpenAPI validator reports every structural problem with a JSON Pointer to the exact node. It parses and validates in your browser, so an unreleased specification never leaves your machine.

The rule that makes the result worth trusting is that nothing checked is silently skipped. A $ref that points at another file is not fetched — that would need a network request and the file you do not have — so instead of quietly ignoring it, the tool reports that everything behind it is unvalidated. A validator that skims half a document and prints “valid” is worse than no validator, because it converts an unknown into a false assurance.

Errors are things the specification requires: a missing info.title, a response with no description, a path parameter that no parameter declares, a $ref that does not resolve, a component name using characters the spec forbids. Warnings are things that will generate but will hurt you later: an operation with no operationId, an operation documenting no successful response, a request body on a GET.

It also knows where 3.0 and 3.1 differ, because that is where most confusion lives. `paths` is required in 3.0 and optional in 3.1 if the document has webhooks or components instead. `responses` is required on every 3.0 operation and not in 3.1. A Swagger 2.0 document is recognised and named as such rather than being reported as a broken OpenAPI 3 file.

Reads YAML or JSON, choosing by content and reporting syntax errors with a line number
Every issue located by JSON Pointer, with RFC 6901 escaping
Path templating checked both ways — every {placeholder} needs a parameter, and every path parameter must be required
Local $ref resolution, with dangling references reported as errors
External $ref reported as unchecked rather than skipped
Security requirements checked against the schemes actually defined
Per-scheme rules for apiKey, http, oauth2 and openIdConnect
Duplicate operationId detection, naming the other operation
Version-aware: 3.0 and 3.1 rules differ, and Swagger 2.0 is identified by name

How to use it

Paste your specification, or open the .yaml or .json file directly.
Fix the errors first — they are things the specification requires, and most tooling will refuse the document until they are gone.
Read the warnings before dismissing them. A missing operationId is not a spec violation but it changes every generated client method name whenever a path changes.
Use the JSON Pointer under each issue to find the node — it is the path your editor's outline and most spec tooling use.
Check the operations list to confirm the document describes what you think it does.

Real-world use cases

API product & platform teams

Validate the specification before it becomes the contract external partners build against — a missing description or an unresolved $ref is cheap to fix now and expensive once a client generator has shipped against it.

Backend developers

Check a hand-written or framework-exported spec (FastAPI, NestJS, Spring) before publishing it, catching the path-parameter and duplicate-operationId mistakes that a schema-first framework's own export step does not always catch.

Frontend & client developers

Confirm a specification is valid before pointing a code generator at it, since most generators fail with a stack trace rather than a useful message on a document with a dangling reference or a missing required field.

QA & API testers

Sanity-check a spec pulled from a bug report or a colleague's branch before writing contract tests against it, so a test failure means the API is wrong rather than the spec being malformed.

DevOps & CI/CD engineers

Reason about what a spec-lint CI step should reject, using the same error/warning split this tool renders, before wiring an equivalent check into a pipeline with a linter like Spectral.

Examples

A path parameter nothing declares

Input

paths:
  /users/{id}:
    get:
      responses:
        "200": { description: OK }

Output

error  Path "/users/{id}" uses {id} but no parameter declares it.
       /paths/~1users~1{id}/get

The single most common OpenAPI mistake. Code generators produce a method that cannot fill in the URL.

A response with no description

Input

responses:
  "200":
    content:
      application/json: {}

Output

error  Response 200 has no description.

`description` is required on every response object. Most tools accept the document anyway and then render a blank row.

A reference that does not resolve

Input

schema:
  $ref: "#/components/schemas/User"

Output

error  "#/components/schemas/User" does not resolve.

Usually a rename, or a schema defined under `definitions` — which is Swagger 2.0's location, not OpenAPI 3's.

A Swagger 2.0 document

Input

swagger: "2.0"
info: { title: Old API, version: "1" }

Output

error  This is a Swagger 2.0 document, not OpenAPI 3.

Named rather than reported as a hundred missing fields. The structures are genuinely different — definitions, basePath and produces are all 2.0.

Common errors

Message	Cause	Fix
Missing the `openapi` version string.	The document has no top-level openapi field, or it is a Swagger 2.0 file which uses `swagger` instead.	Add openapi: "3.1.0". If it really is Swagger 2.0, convert it — the two are not compatible.
Path parameter must have required: true	A parameter with in: path but no required: true.	The spec makes it mandatory — a path parameter cannot be omitted, so declaring it optional is meaningless. Add required: true.
operationId ... is used more than once.	Two operations share an operationId, often after copying a path block.	Generated clients name their methods after this, so a duplicate produces either a compile error or a silently overwritten method. The error names the other operation.
Component name contains characters the spec does not allow.	A key under components using spaces or punctuation. The spec constrains them to ^[a-zA-Z0-9._-]+$.	Rename it. A name outside that set cannot be written as a $ref without escaping, so nothing can reference it.
`paths` is required in OpenAPI 3.0.	A 3.1-style document declaring only webhooks or components, but with openapi: 3.0.x at the top.	Either add paths: {} or move to 3.1, which made paths optional when the document describes something else.
A GET with a request body is defined but poorly supported.	requestBody on a GET, HEAD or DELETE operation.	Allowed by the spec, dropped in practice by proxies, browsers and fetch itself. Use query parameters, or POST.

Frequently asked questions

›Is my specification uploaded?

No. YAML and JSON parsing and all validation run in your browser. That matters for a specification more than for most documents — it typically describes an API that is not public yet, including internal endpoints and field names. You can confirm nothing is transmitted by validating with your network disconnected.

›Does it follow $ref into other files?

No, and it tells you so for each one. Following an external reference means fetching a file this page does not have, which would require either uploading your specification or making requests on your behalf. Instead each external $ref is reported as unchecked, so you know precisely which parts of the document were validated. Bundle the specification into a single file — with redocly bundle or swagger-cli bundle — to have all of it checked.

›What is the difference between an error and a warning here?

An error is something the specification requires: a missing required field, a reference that does not resolve, an invalid enum value. Most tooling will reject the document. A warning is valid but consequential — an operation with no operationId, an operation that documents no 2xx response, a body on a GET. Warnings never make a document invalid, which is why they are separated rather than mixed in.

›Does it validate the JSON Schemas inside the specification?

It checks their structure and resolves their references, but it does not run them as schemas. If you want to check that an example validates against its schema, the JSON Schema Validator on this site does that against draft 2020-12, which is the dialect OpenAPI 3.1 uses.

›Which OpenAPI versions does it support?

3.0.x and 3.1.x, with the rules that actually differ applied per version — paths being optional in 3.1, responses not being required in 3.1, and the type-as-array form that 3.1 inherited from JSON Schema 2020-12. Swagger 2.0 is detected and named rather than being reported as a broken 3.x document.

›Why does it warn about a missing operationId?

Because generated clients fall back to a name derived from the method and path. That means renaming a path renames the method in every generated SDK, which is a breaking change for consumers who never touched anything. An explicit operationId decouples the two, which is why it is worth adding even though the spec makes it optional.

›Can I validate a Swagger 2.0 file here?

No. It is detected and named so you are not left guessing, but the structures are genuinely different — definitions instead of components/schemas, basePath, produces and consumes, body parameters instead of requestBody. Convert it first; the OpenAPI Diff Checker on this site can then show you what changed.

›Does it check that my specification matches my actual API implementation?

No — it checks the document against the OpenAPI specification itself, not against a running server. A spec can be perfectly valid here and still describe an endpoint that returns a different shape in production. Contract testing against a live API is a separate concern; this tool answers whether the document is well-formed and internally consistent.

Last updated July 27, 2026