How to Validate OpenAPI YAML and JSON

Practical recommendation

A YAML parser can accept a document that is not OpenAPI. After syntax succeeds, check the version, info, paths, operations, schemas, references, and organization rules.

Treat errors and quality warnings separately. Missing summaries may not invalidate the specification but still reduce documentation and testability.

Working example

openapi: 3.1.0
info:
  title: Synthetic API
  version: 1.0.0
paths:
  /health:
    get:
      operationId: getHealth
      summary: Check health
      responses:
        '200': { description: Healthy }

Review checklist

• Syntax errors include source positions.
• Required root and info fields exist.
• Every local $ref resolves.
• Operation IDs are unique and stable.
• Examples use synthetic data.

Compatibility, security, and limitations

• Document validation does not call the API.
• Remote references are intentionally not fetched by DevPouch.
• Vendor extensions require their owner's rules.

Validation has distinct layers

First parse YAML or JSON and report source positions. Then validate required OpenAPI structure and version. Resolve local references and evaluate operation-level quality rules. Finally, run contract tests against the deployed implementation. Each layer produces different evidence and none should be presented as a substitute for the next.

Warnings such as missing summaries can be release-relevant without making the document structurally invalid. Keep errors and warnings filterable and make the rule identifier stable enough for teams to discuss or suppress intentionally.

Deterministic validation fixtures

• A minimal valid OpenAPI 3.0 document and a minimal valid 3.1 document.
• Invalid YAML and valid YAML with missing OpenAPI fields.
• Duplicate operation IDs and missing summaries/descriptions.
• Resolved, undefined, circular, and remote references.
• Request body, parameters, responses, and component schemas.
• A file at and above the local size limit.

References

• OpenAPI Specification 3.1.1
• YAML 1.2.2 Specification

FAQ

Related guides