S SCHEMA.BIZ

Last updated:

OpenAPI Validator

This OpenAPI validator checks Swagger and OpenAPI specs against the official schemas.

Checked in your browser as you type. A file you open is read here and never uploaded.

How to use the OpenAPI validator

Paste a spec into the editor, open a YAML or JSON file, or load one of the samples. The validator reads the swagger or openapi field to tell the version, checks the document against the official JSON Schema for that version, then runs the checks a schema can't express. The results list every problem with its line and column, where it is in the document, and how to fix it; the line numbers in the editor's margin turn red for errors and amber for warnings, and the line link moves the cursor to the problem. It checks again as you type.

The samples are a small pet store written three times, as Swagger 2.0, OpenAPI 3.0 and OpenAPI 3.1, all valid, and a broken 3.0 spec with ten mistakes taken from the list below. "Copy a share link" makes a link that opens the same spec, and "Open in the OpenAPI Editor" moves it to the editor, with its live documentation preview. A spec over 1 MB, such as a large public API's, isn't shown in the editor, but it's checked in full, and each problem still gives its line in the file.

The second tab, "Validate a response", checks a real response against the spec: choose the operation, type the status code and paste the body, and optionally the response headers. Switch it to "A request" to check a request body, its query string and its headers against the operation's request body and parameters. It uses the spec from the first tab, so fix the spec's errors first.

What the official schemas check, and what they don't

The OpenAPI Initiative publishes a JSON Schema for each version of the specification at spec.openapis.org. Swagger 2.0 and OpenAPI 3.0 are described in JSON Schema Draft 4, 3.1 and 3.2 in Draft 2020-12, and the validator runs each with Ajv, using the right draft for each. The schemas catch the structural mistakes: a missing info or paths, a response without a description, a field in the wrong place or misspelled (only fields starting with x- may be added), a value of the wrong type, and a parameter that is neither a query, header, path or cookie parameter.

What a JSON Schema can't do is compare one part of the document with another. So the validator also checks that every internal $ref points to something, that each {name} in a path has a path parameter and each path parameter appears in its path, that no parameter, operationId or templated path is listed twice, that every security scheme a requirement names is defined, and that server URLs are URLs whose variables are defined. In OpenAPI 3.1 and 3.2, where an operation may legally have no responses, it warns when one has none, and it warns about components that nothing refers to.

In 3.1 and 3.2, the official schema accepts any object as a Schema Object, because those are full JSON Schema. The validator checks each one against the JSON Schema 2020-12 meta-schema, so type: strin or a negative minLength is reported there too. Ajv's error output for OpenAPI 3.0 is noisy, because the schema offers alternatives such as "a Response or a $ref" for most fields; the validator works out which alternative you meant and reports only its errors.

It doesn't lint style: missing summaries, operationId naming, or whether every operation documents its error responses are linter rules, not validity. The CI tools below cover them.

Swagger 2.0 vs OpenAPI 3.0 vs 3.1

Swagger 2.0OpenAPI 3.0OpenAPI 3.1 and 3.2
First lineswagger: "2.0"openapi: 3.0.3openapi: 3.1.1
Servershost, basePath, schemesservers, with variablesservers, with variables
Request bodya parameter with in: bodyrequestBody, by media typerequestBody, by media type
Reusable partsdefinitions, parameters, responsescomponentscomponents, plus pathItems
Schemasa subset of JSON Schema Draft 4an extended subset of Draft 4/5JSON Schema 2020-12
Nullnot expressiblenullable: truetype: [string, "null"]
Webhooksnono (callbacks only)yes, top-level webhooks

The step from 2.0 to 3.0 reorganised the document; the step from 3.0 to 3.1 mostly changed schemas. 3.2, published in September 2025, adds to 3.1 (a query method among others) without breaking it. A spec doesn't become 3.1 by changing its first line: nullable stops working, and boolean exclusiveMinimum must become a number. The validator checks a spec against the version it declares, so after an upgrade the schema errors show what still needs converting.

The 10 most common spec errors and how to fix them

  1. A response without a description. Every Response Object needs a description, even when the response has no body. It's the most common error the official schema reports.
    responses:
      "204": {}
    responses:
      "204":
        description: Deleted
  2. A $ref that points nowhere. The schema can only check that a $ref is a string. The validator follows every internal reference and suggests the nearest existing name when it's a typo.
    $ref: "#/components/schemas/Pets"
    $ref: "#/components/schemas/Pet"
  3. A path parameter that isn't declared. Each {name} in a path needs a parameter with in: path, on the path or on every operation under it.
    /pets/{petId}:
      get:
        responses: ...
    /pets/{petId}:
      parameters:
        - name: petId
          in: path
          required: true
          schema:
            type: integer
  4. A path parameter without required: true. Path parameters are always required, and the spec makes you say so.
    - name: petId
      in: path
      schema:
        type: integer
    - name: petId
      in: path
      required: true
      schema:
        type: integer
  5. A version written as a number. YAML reads an unquoted 1.0 as the number 1, and info.version must be a string. The same goes for openapi: 3.0 written without its patch number.
    info:
      version: 1.0
    info:
      version: "1.0"
  6. OpenAPI 3.1 syntax in a 3.0 spec. 3.0's Schema Object takes one type and doesn't know const, examples or $defs. Either write 3.0 syntax, or change the openapi field to 3.1.0.
    openapi: 3.0.3
    ...
    type: [string, "null"]
    openapi: 3.0.3
    ...
    type: string
    nullable: true
  7. A parameter without in. Without in, a parameter has no location; a parameter is identified by its name and location together.
    - name: limit
      schema:
        type: integer
    - name: limit
      in: query
      schema:
        type: integer
  8. The same operationId twice. operationIds must be unique: code generators use them as function names, and the second one overwrites the first.
    /pets:
      get:
        operationId: getPet
    /pets/{petId}:
      get:
        operationId: getPet
    /pets:
      get:
        operationId: listPets
    /pets/{petId}:
      get:
        operationId: getPet
  9. A security scheme used but never defined. Each name in a security requirement must match a scheme under components.securitySchemes (securityDefinitions in Swagger 2.0).
    security:
      - apiKey: []
    components:
      securitySchemes:
        apiKey:
          type: apiKey
          in: header
          name: X-API-Key
  10. A server URL without a scheme. Without https://, a host and port read as a relative path. Use a full URL, or a path like /v1 relative to where the spec is served.
    servers:
      - url: api.example.com:8080/v1
    servers:
      - url: https://api.example.com:8080/v1

The broken sample spec has all ten but the fourth, plus a component no $ref uses: load it to see how each is reported.

Validating responses against the spec

A valid spec can still describe an API that behaves differently. Paste a real response into the second tab to see whether it matches: a field the schema requires that the API leaves out, a number sent as a string, or an enum value the spec doesn't list are reported as JSON pointers into the body, such as /items/0/status, with a suggested fix. The sample response, a pet whose id is a string and whose status is "adopted", shows three of them. Requests work the same way, and a property marked readOnly in a request body is flagged as one the client shouldn't send.

How to validate in CI

A browser tool is for finding and fixing problems; your build should catch them before they ship. Two open-source command-line tools validate a spec and lint it against style rules, and both exit with an error code when the spec has errors, which fails the build:

  • Spectral (Stoplight) needs a ruleset; the built-in OpenAPI one checks Swagger 2.0 and OpenAPI 3 documents. Its --format github-actions option annotates the problems on the pull request.
  • The Redocly CLI lints with its recommended rules by default, and its bundle command joins a spec split over several files into one.
# .spectral.yaml
extends: ["spectral:oas"]
npx @stoplight/spectral-cli lint openapi.yaml
npx @redocly/cli lint openapi.yaml

When a spec changes, the Breaking Change Detector compares the old and new versions and lists the changes that would break clients, and the API versioning guide covers what to do about them.

FAQ

Which versions does the validator check?

Swagger 2.0, and OpenAPI 3.0, 3.1 and 3.2, in YAML or JSON. It reads the swagger or openapi field and uses the official JSON Schema for that version, published at spec.openapis.org: Swagger 2.0 (2017-08-27), OpenAPI 3.0 (2024-10-18), OpenAPI 3.1 (2026-08-03), OpenAPI 3.2 (2026-08-30).

Is my spec uploaded anywhere?

No. The spec is parsed and checked in your browser (in a background thread where the browser allows one), and a file you open is read there too. The validator records what kind of check ran: the spec's version, its counts of paths and operations, the numbers of errors and warnings, and the codes of the problems found, never the spec, its paths, titles or server addresses, or a response body. See the privacy policy.

Why does a spec that passes the official schema still show errors?

The JSON Schemas check the shape of the document, not its meaning. They can't tell that a $ref points to nothing, that {petId} in a path has no matching parameter, that two operations share an operationId, or that a security requirement names a scheme nobody defined. Those come from the validator's own checks, marked "spec rule" in the results.

Does it follow external $refs?

No. A $ref to another file or a URL is reported once per file as a note, and its target isn't fetched or checked. To check a spec split over several files, bundle it into one first, for example with the Redocly CLI's bundle command.

How does response validation work?

Pick an operation and a status code, paste the body, and the validator finds the matching response (the exact code, then a range such as 4XX, then default) and checks the body against its schema. OpenAPI 3.0 and Swagger 2.0 schemas are converted to JSON Schema first: nullable allows null, readOnly properties aren't expected in a request and writeOnly ones in a response, and discriminator is noted but not used, since oneOf and anyOf decide. Response headers and a request's query string and headers are checked too.

Can I share a spec with someone?

"Copy a share link" puts the spec, compressed, after the # in the page's address. Browsers don't send that part to a server, so the link works without anything being stored, but anyone who has it can read the spec. Specs too large for an address can't be shared this way.

Related tools