OpenAPI / Swagger Validator

Frequently asked questions

Does this validate against the full OpenAPI schema?

Yes. The document is checked against the official JSON Schema published by the OpenAPI Initiative for its version: Swagger 2.0, OpenAPI 3.0, 3.1, or 3.2. That covers required fields, allowed values, types, and unknown fields everywhere in the document. One exception: for 3.1 and 3.2, the official schema checks only that each Schema Object is an object, and leaves its contents to a separate JSON Schema dialect, so a typo inside components.schemas is caught in 3.0 but not in 3.1.

What does it check beyond the schema?

Rules that compare parts of the document with each other, which a JSON Schema can't express: every internal $ref must point at something that exists, and no two operations may share an operationId. It also warns about paths that declare no operations.

Why do other validators show so many more errors?

The official schemas describe many fields as "a $ref or the real object" and parameters as "one of path, query, header, or cookie". A standard validator reports every alternative that didn't match, so one mistake can produce eight errors. This tool works out which alternative you meant and shows only its problem.

Why is my version field rejected?

openapi needs a full version with a patch number, like "3.1.0". In YAML, put it in quotes: an unquoted openapi: 3.0 is read as the number 3.

Can I paste YAML, or does it need to be JSON?

Either. OpenAPI specs are usually written in YAML, and the validator parses it directly.

Is my spec uploaded anywhere?

No. Validation runs in your browser tab. The YAML parser and the schema for your version download the first time you validate, and nothing you paste is sent to a server.