How to use OpenAPI Validator
- Paste the specification.
- Read the status line, then fix errors first (they break tooling) and warnings second.
- Download the problem table as CSV to track fixes in a review.
OpenAPI Validator features
- OpenAPI 3.0, 3.1 and Swagger 2.0 in JSON or YAML with line-accurate parse errors
- Required fields, servers/host syntax, path templates vs. path parameters, parameter locations, request bodies and responses
- Duplicate operationIds, unresolved local $ref pointers, unused components, undefined security schemes, unused or undeclared tags
- Schema checks: unknown types, arrays without items, min/max ordering, required properties that do not exist, 3.0 nullable vs 3.1 type arrays
- Problems sorted by severity with JSON Pointer locations
- Document statistics: paths, operations, parameters, responses, schemas, security schemes, tags, servers
OpenAPI Validator example
Catch a broken path parameter
Input:
paths:
/orders/{orderId}:
get:
parameters:
- name: id
in: path
required: true
schema: { type: string }
responses:
"404": { description: Not found }Output:
error #/paths/~1orders~1{orderId}/get/parameters/0/name Path parameter "id" does not appear in the path template "/orders/{orderId}".
error #/paths/~1orders~1{orderId}/get/parameters Path template uses {orderId} but no path parameter "orderId" is defined.
warning …/responses No 2xx or default response is documented.Frequently asked questions about OpenAPI Validator
What is checked?
Required top-level fields (openapi/swagger, info.title, info.version, paths), server and host syntax, path templates vs. path parameters, parameter locations and required flags, request bodies, responses with descriptions and valid status codes, duplicate operationIds, unresolved local $ref pointers, unused components, security requirements that reference undefined schemes, tag consistency and schema keyword sanity (array items, min/max ordering, 3.0 vs 3.1 nullability).
What is the difference between errors, warnings and hints?
Errors violate the specification and will break code generators or gateways. Warnings are allowed but risky or unhelpful (missing operationId, no 2xx response, unused schema). Hints are documentation-quality suggestions.
Does it validate examples against schemas?
No. Validation is structural. Use the JSON Schema Validator tool to check example payloads against an individual schema.
Are external $ref files fetched?
No. References to other files or URLs are reported as unverifiable hints; everything else is validated offline in your browser.
Technical notes
Locations are JSON Pointers (RFC 6901) with ~1 escaping for slashes so they can be used directly with other tooling. The validator is structural and deliberately fast (single pass, no network), which makes it suitable for live validation while editing.