How to Validate an OpenAPI or Swagger Spec

What OpenAPI and Swagger Actually Are

OpenAPI is the standard format for describing REST APIs. An OpenAPI document defines the API's endpoints, the parameters each one accepts, what the request body should look like, what responses to expect, and how authentication works. The document is written in JSON or YAML and is machine-readable — tools can generate client SDKs, server stubs, API documentation, and test mocks directly from it.

Swagger is the older name for the same format. The spec originated at Wordnik, was adopted widely as the Swagger Specification, and was donated to the OpenAPI Initiative in 2016 under the name OpenAPI. In practice, Swagger 2.0 and OpenAPI 3.x are the two versions you will encounter. Swagger refers specifically to version 2.0, while OpenAPI refers to 3.0 and later.

When people say they are writing a Swagger spec or an OpenAPI spec, they typically mean the same type of file. Whether it is valid depends on which version it claims to follow and whether the document's structure and fields match that version's rules throughout.

Why Validation Matters Before You Publish

An invalid spec causes downstream failures that are difficult to diagnose because error messages usually come from whatever consumed the spec, not from the spec itself. A code generator that receives an invalid spec may produce broken client code, fail silently, or emit an error that points at the generator. An API gateway import that fails because of a spec error looks like a gateway problem.

Documentation tools that render OpenAPI specs will either reject an invalid spec outright or render it incorrectly in ways that are confusing to your API consumers. If someone imports your spec into their toolchain and gets errors, they will report the problem as a tool failure rather than looking at the spec.

Catching validation errors before publishing takes seconds. Tracking down a broken SDK, debugging a gateway import failure, or explaining to an API consumer why the documentation doesn't match the actual endpoints can take hours. Running a validator early is consistently the faster path.

OpenAPI 3.x vs Swagger 2.0: Which Version Do You Have?

The version is declared at the top of the document. Swagger 2.0 documents open with the swagger field set to 2.0. OpenAPI 3.x documents open with the openapi field set to the version number — 3.0.0, 3.1.0, or 3.2.0. If neither of those fields appears, the document is already missing a required field before any other rule is checked.

Swagger 2.0 and OpenAPI 3.x use different field names for the same concepts. In Swagger 2.0, the server address is defined using host and basePath fields. OpenAPI 3.x uses a servers array. In Swagger 2.0, request bodies are defined as body parameters inline on an operation. OpenAPI 3.x uses a separate requestBody field. These structural differences mean a document written for one version is not valid for the other, and mixing fields from both is one of the most common sources of validation errors.

OpenAPI 3.1 introduced full alignment with JSON Schema, which changed how some type definitions work compared to 3.0. The nullable keyword is valid in 3.0 but not in 3.1 — in 3.1, you express the same thing using a type array that includes null. A version-aware validator catches these version-specific mismatches automatically.

What an OpenAPI Validator Checks

The foundational check is structural: are all required fields present, are values the correct type, and are enumerated values within their allowed set. The info object requires at minimum a title and a version. Every path must have at least one valid operation. Every operation requires a responses object with at least one defined status code.

Beyond structure, the validator checks schema references. OpenAPI specs use a ref notation to point to shared schema definitions within the document. A reference that points to a definition that does not exist — because it was renamed, deleted, or never added — is a common failure that text editors will not flag. These broken references only surface when the spec is parsed by a tool that tries to resolve them.

Response status codes in OpenAPI must be written as quoted strings, not bare numbers. Other common type mismatches include string fields that received numeric values, boolean fields written as quoted strings, and example values that don't match the schema type they are supposed to illustrate. All of these pass a visual review and fail under validation.

Common Validation Errors and How to Fix Them

Missing required fields are the most frequent error. The usual culprits are a missing version inside the info object, no responses on an operation, or an empty paths object. Read the error message carefully — the path it reports points to the exact location in the document, not just the category of problem.

Broken schema references are the second most common issue. Search the entire document for the exact broken reference string and update every occurrence. If a component was renamed, every reference to the old name needs to be updated — not just the first one you spot.

YAML indentation errors are technically a YAML syntax problem rather than an OpenAPI problem, but they prevent the spec from being parsed at all. If the validator reports a structural error before reaching any OpenAPI-level rules, validate the YAML separately first to isolate whitespace or indentation issues from spec-level problems.

Version conflicts — where the version number at the top doesn't match the fields used throughout — require picking one version to target and making the structure consistent. Choose the version your toolchain needs, check the migration notes for any field name changes between versions, and update accordingly.

Frequently Asked Questions

What is the fastest way to validate an OpenAPI spec? Paste the JSON or YAML content into an online OpenAPI validator and run it. The result will show the detected version, whether the spec passed, and the exact location of any errors.

What is the difference between a JSON validator and an OpenAPI validator? A JSON validator checks whether the text is syntactically valid JSON. An OpenAPI validator checks whether the content follows the OpenAPI specification rules — required fields, valid schema structures, proper reference targets, and version-specific constraints. A spec can be syntactically valid JSON and still be an invalid OpenAPI document.

My spec passes validation but my code generator still fails — why? Code generators sometimes have requirements that go beyond the OpenAPI spec. Some require an operationId on every operation, don't support specific schema patterns, or expect vendor extensions. Passing OpenAPI validation means the spec is structurally correct; tool-specific requirements are separate.

What is the difference between OpenAPI 3.0, 3.1, and 3.2? OpenAPI 3.0 replaced Swagger 2.0 with a cleaner structure. OpenAPI 3.1 aligned schema definitions with JSON Schema 2020-12, changing how nullable types are expressed. OpenAPI 3.2 added webhooks as a first-class concept. Most tools support 3.0 and 3.1 well; 3.2 support varies.

Do I need to revalidate after every change? Validating before committing or sharing is a reasonable baseline. For larger changes — restructuring shared components, changing schema definitions, or updating the version number — validate after each change while the context is still fresh.

Can I preview what my API documentation will look like from the spec? If the validator includes a documentation preview, yes. Tools that render the spec in a documentation viewer show you the endpoint layout, parameter descriptions, and response structures before publishing — useful for catching content issues that structural validation doesn't cover.

Why does YAML seem to cause more validation errors than JSON? Because YAML is sensitive to indentation and whitespace in ways that are invisible in most editors. Mixed tabs and spaces, wrong indent levels, and unquoted strings containing special characters all produce parse failures. JSON's stricter syntax means errors are usually explicit — a missing quote or comma — rather than invisible whitespace problems.

Is it safe to paste an internal API spec into an online validator? It depends on the tool. Look for one that is clear about not storing uploaded content after processing. For sensitive or internal specs, check the tool's privacy policy before pasting anything.