OpenAPI validation guide

A useful OpenAPI check is layered. Parsing, structural validation, reference resolution, semantic review, and compatibility analysis answer different questions and should produce different errors.

1. Parse YAML or JSON first

Before applying OpenAPI rules, confirm the document is valid YAML or JSON. YAML indentation, duplicate keys, tabs, and ambiguous scalar values can change the parsed object. JSON comments and trailing commas fail before OpenAPI validation begins. Preserve the source line and column so authors can repair the document without searching the entire file.

2. Confirm the document version and root fields

OpenAPI 3 documents require an openapi version, an info object, and a paths object. Use the OpenAPI Validator for a fast structural preflight. A Swagger 2 document uses different fields and cannot be migrated by replacing swagger: "2.0" with an OpenAPI 3 version. Request bodies, servers, reusable components, and security definitions must be translated deliberately.

3. Resolve every reference in context

A valid $ref must point to an existing object of the expected kind. Check local JSON Pointers, escaped path segments, relative files, and allowed remote references. Detect cycles without rejecting legitimate recursive schemas. For security, do not let an untrusted document make unrestricted network or file-system requests; use an allowlist, size limits, timeouts, and private-network protections.

4. Validate operations, parameters, and responses

Each operation should have stable identifiers where tooling depends on them, valid parameters, and at least one meaningful response. Path parameters declared in a URL template must be present and required. Check that request bodies declare appropriate media types and that response descriptions and schemas match what clients receive. Duplicate or ambiguous routes deserve a warning even when the base schema accepts them.

5. Validate component schemas

Schema validity is not the same as useful API design. Check required properties, nullable behavior, enum values, formats, composition keywords, and additionalProperties. OpenAPI 3.0 and 3.1 use different schema dialect rules. Configure tools for the declared version instead of assuming every JSON Schema keyword behaves identically.

6. Compare the contract with reality

A document can pass every structural rule and still disagree with the server. Add contract tests for representative requests and responses, or validate captured traffic after redacting sensitive data. Verify status codes, media types, headers, and required response fields. Treat examples as test inputs where possible rather than decorative documentation.

7. Detect compatibility changes

Validation asks whether one document is internally acceptable. A diff asks whether moving from the old document to the new one can break consumers. Removed operations, newly required request properties, narrowed enums, and removed response properties may be breaking. Run the comparison against an immutable base revision and separate detected severity from the policy that decides whether CI fails.

A practical CI order

1. Parse the source and fail with precise syntax locations.
2. Validate the OpenAPI version and structural rules.
3. Resolve references within strict resource limits.
4. Run organization lint rules and contract fixtures.
5. Compare against the pull request base artifact.
6. Publish a readable report and fail only according to policy.

Frequently Asked Questions

Related Tools and Guides