OpenAPI / Swagger Validator

OpenAPI: The Contract Your Whole Stack Depends On

A modern HTTP API has a lot of consumers, frontend SDKs, mobile clients, third-party integrations, your own internal services, documentation portals, mock servers, test runners. Without a machine-readable contract, every consumer reinvents the same understanding of "what calls this API supports and what they return." OpenAPI is that contract. Get it right and your codegen, docs, mocks, and tests all stay synchronized for free. Get it wrong and every downstream tool breaks subtly.

This validator catches the spec-level problems before they cascade.

What "Valid" Actually Means

There are three layers of OpenAPI correctness:

1. JSON well-formed. Balanced braces, valid types. Any JSON parser catches these.
2. Conforms to the OpenAPI meta-schema. Top-level structure matches what the spec says: required fields present, value types correct (string where string, number where number). This is what the JSON Schema validation of the meta-schema gives you.
3. Semantically consistent. Internal references resolve, IDs are unique, every operation is reachable, security references match definitions. The meta-schema doesn't catch these because they're cross-document constraints.

This tool covers all three. You'd be surprised how many "valid" OpenAPI specs in the wild have unresolved $refs that crash codegens.

The Most Common Spec Mistakes

1. Missing operationId. Every operation needs a unique operationId for codegen. Without it, generators synthesize names from paths and methods (paths_users_id_get), which break the moment you reorganize paths. With it, names are stable across refactors.

2. Operations with no responses. The spec requires at least one response per operation. Many specs only define the happy path (200); the generator then doesn't know how to handle 4xx/5xx. Best practice: define 200, 400, 401, 403, 404, 500 explicitly, plus a default for unspecified errors.

3. Unresolved $ref. $ref: '#/components/schemas/User' requires #/components/schemas/User to actually exist. Typos here are silent in JSON validation but explode at codegen. Common when refactoring component names without updating references.

4. Duplicate operationId. Codegens use operationId as the function name; two operations with the same operationId means one of the methods gets overwritten or the generator errors out.

5. Inconsistent path parameters. A path like /users/{userId}/posts/{postId} must define both userId and postId parameters with in: path and required: true. Missing one is a silent fail in many validators but breaks Postman, Insomnia, and most codegens.

6. Security defined globally but never used at operation level. Or vice versa. Either pattern causes generators to either skip auth (and produce broken clients) or apply it everywhere (and crash on public endpoints).

7. Schema examples not matching the schema. type: integer with example: "five", passes JSON validation (since the example is a string), but mocks generated from it produce strings where integers are expected.

8. Missing servers block. Clients don't know where to send requests. Defaults vary across tools; better to be explicit.

OpenAPI 3.1 Specifically

3.1 is fully JSON Schema 2020-12 compatible. Practical implications:

• Schemas in your spec can use any JSON Schema 2020-12 feature (if/then/else, unevaluatedProperties, prefixItems, etc.). Earlier versions had a custom dialect that was almost-but-not-quite JSON Schema.
• Webhooks are first-class. Sibling to paths. Useful for APIs that send callbacks.
• JSON Schema null support. { "type": ["string", "null"] } instead of the 3.0 hack { "type": "string", "nullable": true }. Cleaner but tooling support varies.
• License identifier uses SPDX. license: { identifier: "MIT" } replaces the older URL-based reference.

If your tooling supports 3.1, use it. If you're stuck on 3.0 because of older codegens, that's fine, the validator handles both.

Style Guides and Linting

Beyond spec validity, teams care about style: naming conventions, required descriptions, response shape consistency. Tools like Spectral and Redocly Lint add custom rule sets on top of the validator's core checks. Common rules:

• Every operation must have a description and at least one tag.
• Path segments use kebab-case or snake_case (pick one, enforce).
• Resource names plural (/users), not singular.
• Response schemas don't reference single-use components (inline them).
• Error responses follow a consistent shape (Problem Details for HTTP APIs, RFC 7807).

This validator handles correctness; Spectral/Redocly handle house style. Run both in CI for production specs.

Code Generation: The Real Test

A spec's validity is best confirmed by running a code generator against it. If your spec produces a clean client SDK, it's likely correct. If the generator errors or produces broken code, your spec has issues the validator may not have caught.

Common generators:

• openapi-typescript (TS types only, no runtime).
• openapi-fetch / openapi-zod-client (typed clients).
• NSwag / OpenAPI Generator (multi-language: C#, Java, Go, Python, Rust).
• Orval (TS with React Query / SWR integration).
• prism (Stoplight's mock server, generates mocks from spec).

Run your spec through one of these. The first error tells you the most pressing issue; iterate.

Common Generator Crashes Worth Knowing About

• Duplicate operationId → most generators silently overwrite or crash.
• Operations with no responses → some generators skip the operation entirely.
• additionalProperties set wrong → Java/C# generators may produce broken POJOs.
• oneOf / anyOf with no discriminator → TS generators may produce huge union types that break tooling.
• Recursive schemas without proper $ref → infinite loops in some generators.

Privacy

Validation runs entirely in your browser. The OpenAPI metaschema and rule set are bundled in the page. Your spec, which often reveals upcoming endpoints, internal data structures, partner integration details, or authentication mechanisms, stays in the tab. Open DevTools Network during validation: zero outbound requests.