10 Common OpenAPI Validation Errors, Fixed

Try It Live

Pick a preset below to load a minimal spec engineered to trip one specific check, or paste your own spec to see what it flags. This is the same validation logic — and the same result panel — as the full OpenAPI / Swagger Viewer.

The Ten, Ranked by How Often They Show Up

1. Missing info.version

info.title and info.version are both required by the spec, but version is the one people forget — it's easy to assume the OpenAPI version field (openapi: 3.1.0) covers it. It doesn't; info.version is your API's version (1.0.0, 2024-01-15, whatever scheme you use), completely independent of which OpenAPI spec version the document is written against. Fix: add a version string under info.

2. Duplicate operationId

Every operationId in a document must be globally unique — not unique per path, unique across the entire spec. Copy-pasting an operation as a starting point for a new endpoint and forgetting to rename its operationId is the usual cause. This matters more than it looks: SDK generators use operationId as the method name, so a duplicate either fails codegen outright or silently overwrites one method with another. Fix: rename one of the two.

3. Path/Parameter Mismatch

A path template like /users/{userId} declares a placeholder, but nothing enforces that a matching parameter definition (name: userId, in: path) actually exists — until a strict validator checks for you. This cuts both ways: a {userId} in the path with no matching parameter, or a parameter marked in: path whose name never appears in curly braces in the path string, are both mismatches worth flagging.

4. Missing responses

Every operation must define at least one entry under responses — even a bare '200': { description: OK } satisfies the requirement. An operation with an empty or absent responses object is invalid, and it's a common casualty of specs written top-down (endpoints and request bodies filled in first, responses left as a TODO that never comes back).

5. Invalid or Missing Parameter "in"

Every OpenAPI 3.x parameter must declare exactly where it lives: path, query, header, or cookie. in: body is the classic mistake — it was valid in Swagger 2.0, where request bodies were described as a body-located parameter, but OpenAPI 3.x moved request bodies to their own top-level requestBody field and removed body as a parameter location entirely. Specs migrated from 2.0 by hand (rather than with a converter) carry this over often.

6. Path Parameter Not Marked required: true

Every parameter with in: path must also set required: true — explicitly, even though a path segment is obviously never optional. The spec requires the redundancy anyway, and omitting it is invalid, not just a style nit. Easy to miss when a parameter definition is copied from a query parameter, where required is genuinely optional.

7. Wrong nullable Syntax for the Declared Version

OpenAPI 3.0's nullable: true keyword doesn't exist in 3.1 — a 3.1 document needs type: [string, "null"] instead, following JSON Schema 2020-12's native array-of-types syntax. Using the wrong form for the version you've declared doesn't always produce a loud error; some tooling silently ignores an unrecognized nullable keyword in a 3.1 document rather than rejecting it, which makes the mistake easy to miss until a generated client treats the field as non-nullable. See our OpenAPI 3.0 vs. 3.1 guide for the full breakdown of this and the other version-specific syntax changes.

8. Unresolved or External $refs

A $ref pointing within the same document (#/components/schemas/Pet) resolves reliably in any conformant tool. A $ref pointing at another file (./schemas/pet.yaml#/Pet) or a remote URL depends on that tool being willing and able to fetch external files — many browser-based and CI-embedded validators, ours included, deliberately resolve only inline refs and surface external ones as a separate warning rather than silently failing. If a schema renders as an unexpanded $ref string instead of its actual shape, this is almost always why. Fix: either inline the referenced schema, or use a build step (a bundler like redocly bundle) that resolves external refs into a single self-contained document before distributing or validating it.

9. Path Item With No Operations

A path entry that defines only parameters or a description, with no actual HTTP method (get, post, etc.) underneath it, is structurally valid but pointless — nothing can ever be called at that path. This usually means an operation was deleted during cleanup and the now-empty path entry was left behind.

10. Path Key Doesn't Start With "/"

Every key under paths must be an absolute path starting with / — users instead of /users is invalid, not just non-idiomatic. This one is rare in hand-written specs but shows up reliably in specs generated from route tables that store paths without the leading slash and never add it back during export.

A Faster Loop Than Read-Fix-Reread

All ten of these are cheap to catch before a spec ever reaches a teammate or a generated SDK — paste it into the widget above, or the full OpenAPI / Swagger Viewer, and work down the issue list rather than eyeballing YAML. Once a spec validates cleanly, the next useful check is behavioral, not structural: the API Playground lets you fire real requests at the endpoints a spec describes, so you can confirm the documented responses match what the API actually returns — a class of mismatch no static validator can catch, including status codes; if your response descriptions are vague about what a given code means, our HTTP Status Code reference is a fast way to tighten them up.