Understanding OpenAPI validation
A spec for the spec.
What an OpenAPI document is, what a validator actually checks, and why "the spec parses" and "the API works" are very different statements.
OpenAPI in one paragraph.
OpenAPI (formerly Swagger) is a JSON or YAML document that describes a REST API: base URL, paths, methods, parameters, request/response schemas, authentication schemes, examples. It's the agreed schema language for REST. Current versions are 3.0 (widespread) and 3.1 (modern, JSON Schema 2020-12 compatible). A complete OpenAPI document is enough to generate clients, server stubs, documentation, mock servers, and validation middleware automatically.
What a validator checks.
Three layers. Syntactic: the document parses as JSON or YAML. Structural: it conforms to the OpenAPI meta-schema — required fields exist, types are valid, refs resolve. Semantic: paths use valid characters, operationIds are unique, parameter names match path placeholders, security schemes referenced exist. A passing validator means the document is well-formed; it doesn't mean the described API is a good one.
A worked snippet.
openapi: 3.1.0
info:
title: Users API
version: 1.0.0
paths:
/users/{id}:
get:
summary: Fetch a user by id
parameters:
- name: id
in: path
required: true
schema: { type: integer, format: int64 }
responses:
"200":
description: OK
content:
application/json:
schema: { $ref: "#/components/schemas/User" }
components:
schemas:
User:
type: object
required: [id, email]
properties:
id: { type: integer, format: int64 }
email: { type: string, format: email }
A small but complete OpenAPI 3.1 fragment. The validator confirms the document shape, that the $ref resolves, and that the path parameter name matches.
The three validation layers
parse + structural + semantic
Each layer catches a different category of mistake.
YAML parse → meta-schema → operation-level rules
= Well-formed spec
3.0 vs 3.1, the small print.
3.1 aligns OpenAPI's schema language with JSON Schema 2020-12 — nullable becomes type: [string, "null"] instead of the 3.0 nullable: true property; examples can be arbitrary JSON. The change is technically a simplification but tooling support lags. A validator that targets 3.1 will flag 3.0 documents; one that targets 3.0 won't understand 3.1 nullable syntax. Make sure the validator and the document agree on version.
What validators miss.
A passing validator can't tell you whether the API design is sensible. Whether the paths follow consistent naming. Whether status codes match conventions. Whether response shapes are consistent across endpoints. Whether breaking changes have been introduced versus the previous version. Linters like Spectral add opinionated rules on top of the validator — naming conventions, security defaults, common shapes — that catch the next layer.
From validator to contract tests.
A validated OpenAPI document is also a test asset: send real requests against a running server, validate each response against the schema for that path. Tools like Dredd, Schemathesis, and Postman's contract testing do exactly this. A validated spec that diverges from the running server is worse than no spec — it will mislead anyone who trusts it. Treat the validator as the floor; contract tests are the actual safety net.