OpenAPI Schema Validator Online — Validate and Lint Your API Spec

What Is OpenAPI Schema Validation?

An OpenAPI specification is itself a JSON or YAML document with a defined structure. Validating your OpenAPI spec checks two things: (1) structural correctness — does the document conform to the OpenAPI Specification schema? (2) semantic correctness — are all $ref references resolvable, are response schemas defined, are required fields present?

Invalid specs break Swagger UI rendering, fail code generation, and cause confusing errors downstream. Validating early catches problems cheaply.

How to Validate an OpenAPI Spec Online

1. Paste or upload your spec — JSON or YAML format, OpenAPI 2.0 or 3.x.
2. Select the spec version — OpenAPI 3.1, 3.0.x, or Swagger 2.0.
3. Click Validate — the tool checks structural and semantic correctness.
4. Review errors and warnings — each issue shows the path, rule violated, and suggestion.
5. Fix errors and re-validate — iterate until the spec is clean.

Common OpenAPI Validation Errors

• Unresolved $ref — a component reference ($ref: '#/components/schemas/User') points to a schema that doesn't exist.
• Missing required fields — info, openapi, and paths are required at the top level.
• Invalid HTTP status codes — responses must use valid HTTP status codes as keys.
• Missing operationId — best practice (required by some code generators).
• Duplicate operationIds — each operation must have a unique ID.
• Empty paths object — the spec must define at least one path.

Use Cases

CI/CD Integration

Run OpenAPI validation as part of your CI pipeline using tools like spectral or redocly lint. A spec that fails validation blocks the build, preventing broken API documentation from being deployed.

API Design Reviews

Before sharing an API spec with frontend teams or publishing documentation, validate it to ensure there are no broken references or missing response schemas that would render the documentation incomplete or misleading.

Frequently Asked Questions

What tools can I use to validate OpenAPI specs in CI?

Spectral (by Stoplight) is the most feature-rich linter with customizable rulesets. Redocly CLI provides validation and bundle commands. Swagger Parser validates structure. OpenAPI Generator validates as part of code generation. All are available as npm packages and Docker images.

Is there a difference between linting and validating an OpenAPI spec?

Validation checks whether the document is a valid OpenAPI Specification document (structural correctness). Linting applies additional best practice rules on top: are all endpoints documented? Do responses include examples? Are operationIds meaningful? Linting catches "technically valid but poorly written" specs.

Can I validate OpenAPI 2.0 (Swagger) and OpenAPI 3.x specs?

Yes. Most validators support both. Swagger 2.0 and OpenAPI 3.0.x/3.1 have different schemas. Specify the version when validating, as some rules differ between versions.

How do I fix an "unresolved $ref" error?

Check that the referenced path exists in your spec. For $ref: '#/components/schemas/User', ensure components.schemas.User is defined. Case sensitivity matters — User and user are different. External file references must be accessible.

Does OpenAPI validation check that my implementation matches the spec?

No — OpenAPI schema validation only checks the spec document itself. Contract testing (checking that your live API matches the spec) requires tools like Dredd, Schemathesis, or Pact. These tools make real requests to your API and verify that responses match the spec's defined schemas.