OpenAPI Validator — OpenAPI 3.0 & 3.1

Validate OpenAPI 3.0 / 3.1 specs. Required fields, $ref resolution, response status enforcement, and security scheme correctness — all checked client-side with counts.

Input OpenAPI 3.x (JSON or YAML)

Validation Result

What is an OpenAPI validator?

An OpenAPI validator verifies that an API specification follows the rules defined by the OpenAPI 3.0 or OpenAPI 3.1 standard before tools like Redoc, Swagger UI, openapi-generator, AWS API Gateway, or contract testers consume it. This validator goes beyond presence-of-fields: it walks every $ref, confirms it resolves locally, and validates that each security scheme declares a valid type with the type-specific required fields.

OpenAPI 3.x is the successor to Swagger 2.0; 3.1 aligned the schema dialect with JSON Schema 2020-12, unifying API and data validation tooling. This page targets 3.0/3.1 specifically — for older Swagger 2.0 specs, use the Swagger Validator.

How to validate OpenAPI 3 — 4 steps

Paste OpenAPI 3.x spec. Copy your openapi.yaml or openapi.json into the Input panel.
Click Validate. The tool parses, walks every $ref, and runs structural + security checks.
Review counts & issues. The output lists path / operation / schema / ref counts and any errors or warnings with line numbers.
Fix and re-run. Patch each error and re-run until the badge turns green.

Sample input and output

Input — Pet Store snippet

openapi: 3.0.3
info:
  title: Pet Store
  version: 1.0.0
paths:
  /pets:
    get:
      summary: List pets
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object

Output — Validation result

Valid OpenAPI 3.0.3 specification.

Counts:
  Paths:       1
  Operations:  1
  Schemas:     1
  $refs:       1
  Errors:      0
  Warnings:    0

All structural rules passed.

What this validator checks

1. Required root fields

openapi (must start with 3.0 or 3.1), info.title, info.version, and a non-empty paths object.

2. Per-operation responses

Every operation declares responses with at least one status, and at least one of those statuses is 1xx, 2xx, or default. A spec with only 4xx/5xx responses is technically valid but useless to consumers.

3. $ref resolution

Every local $ref (starting with #/) is resolved against the parsed document. Unresolvable refs become errors. External refs (file or URL) emit warnings — the target document is not fetched.

4. Security schemes

Each entry under components.securitySchemes must declare a valid type (apiKey / http / oauth2 / openIdConnect / mutualTLS) and the type-specific required fields — name + in for apiKey, scheme for http, flows for oauth2, openIdConnectUrl for OIDC.

OpenAPI 3.0 + 3.1 specific

Targets the modern OpenAPI line. For legacy Swagger 2.0, use the Swagger Validator instead.

$ref Resolution

Walks every local $ref and confirms it points to a real target inside the document. Catches typos in component paths.

Security Schemes

Validates apiKey, http, oauth2, openIdConnect, and mutualTLS schemes have all required type-specific fields.

Common use cases

check_circleAPI documentation generation — Redoc, Swagger UI, and Stoplight require valid 3.x specs
check_circleContract testing in CI with Schemathesis, Dredd, or Pact
check_circleClient SDK generation in Java, Go, TypeScript, Python via openapi-generator
check_circleAWS API Gateway / Azure APIM imports — both reject specs with broken $refs
check_circlePre-commit hooks that block bad spec changes from being merged
check_circleMigrating from Swagger 2.0 to OpenAPI 3.x — verify the converted spec is structurally clean
check_circleAuditing security schemes when adopting OAuth2, OIDC, or rotating API keys
check_circleValidating webhooks (OpenAPI 3.1) and the new top-level webhooks: object

Swagger 2.0 vs OpenAPI 3.0 vs OpenAPI 3.1 vs AsyncAPI

Spec	Year	Schema dialect	Use for
Swagger 2.0	2014	Custom subset	Legacy APIs (use Swagger Validator)
OpenAPI 3.0	2017	JSON Schema (subset)	Most production REST APIs today
OpenAPI 3.1	2021	JSON Schema 2020-12	New projects; webhooks, full JSON Schema
AsyncAPI	2017	JSON Schema	Event-driven APIs (Kafka, MQTT, AMQP)

Convert formats or validate Swagger 2.0?

Convert between JSON and YAML, or use the Swagger Validator for legacy specs.

Swagger Validator OpenAPI to JSON OpenAPI to YAML

Frequently Asked Questions

What does the OpenAPI validator check?

It enforces the structural rules an OpenAPI 3.0 / 3.1 spec must satisfy: openapi version field, info.title and info.version, at least one path, every operation having a responses block with a 1xx/2xx success or "default" status, all local $refs resolving to a target inside #/components/, and security schemes declaring valid type plus type-specific required fields (name+in for apiKey, scheme for http, flows for oauth2, openIdConnectUrl for openIdConnect).

How is $ref resolution performed?

For local refs (those starting with #/), the validator splits the JSON Pointer and walks the parsed document. If any segment is missing — typo in the path, schema not yet defined, wrong section — an error is emitted with the unresolvable ref. External refs (file paths or URLs) are flagged as warnings because their target document is not loaded.

Why must every operation have a responses block?

OpenAPI requires it. The responses object tells consumers what HTTP status codes the endpoint can return and what each response body looks like. Without it, code generators cannot emit method signatures, contract testers cannot assert on responses, and Swagger UI shows an empty operation. Add at least one entry — typically "200" with a description.

What security scheme types are supported?

OpenAPI 3.x defines five: apiKey (key in header/query/cookie), http (Basic, Bearer, Digest), oauth2 (with flows), openIdConnect (Discovery URL), and mutualTLS. The validator confirms the type field uses one of these and enforces the type-specific required fields. A bearer JWT for example is type: http with scheme: bearer.

How is OpenAPI 3.0 different from 3.1?

3.1 (released 2021) aligns the schema dialect with full JSON Schema 2020-12 — meaning your OpenAPI schemas can use the same dialect as JSON Schema validators. 3.0 uses a custom subset. 3.1 also adds webhooks (top-level webhooks: object) and allows null in type via type: ["string", "null"]. This validator handles both versions.

Will my spec be uploaded to a server?

No. Validation runs entirely in JavaScript inside your browser. Specs containing example tokens, internal hostnames, or proprietary endpoints stay on your device. Verify in your browser DevTools Network tab — no request is made when you click Validate.

How does this differ from the Swagger Validator?

The Swagger Validator is permissive and accepts both Swagger 2.0 and OpenAPI 3.x with universal structural rules. The OpenAPI Validator is OpenAPI 3.0/3.1-specific and adds $ref resolution, security scheme validation, and stricter response-status checks. Use this one for new APIs; use Swagger Validator for legacy 2.0 specs.

What does "External $ref not validated" mean?

When a $ref points outside the current document — to another file (./schemas/Pet.yaml#/Pet) or a URL (https://example.com/specs/pet.yaml) — the validator cannot fetch the target without making a network request. It surfaces a warning so you know the ref was acknowledged but not resolved. To check external refs, run swagger-cli bundle locally first.