JSON Schema vs OpenAPI Schema: What Is the Difference?

Quick answer: JSON Schema describes and validates JSON values. An OpenAPI document describes an HTTP API, and its Schema Objects describe the request and response data inside it. OpenAPI 3.0 uses its own schema dialect that differs from standard JSON Schema (for example nullable: true and a single-string type), while OpenAPI 3.1 aligns its Schema Object with JSON Schema Draft 2020-12 plus a small OpenAPI-specific vocabulary.

A developer copies a JSON Schema into an OpenAPI specification and the validator rejects it. Another developer upgrades the OpenAPI document and discovers that nullable no longer works as expected. Neither problem is random.

Inspect the JSON structure in the JSON Viewer. This helps with reading the payload; schema validation still requires a separate schema validator.

First, what does JSON Schema do?

Imagine an order sent by your frontend:

{"id":1042,"status":"paid","total":249.5}

JSON Schema can describe the expected structure:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": { "type": "integer" },
    "status": { "type": "string", "enum": ["pending", "paid"] },
    "total": { "type": "number", "minimum": 0 }
  },
  "required": ["id", "status", "total"]
}

The sample JSON may be syntactically valid even if it fails these rules. That is why syntax validation and schema validation are separate tasks. If the keywords above are new to you, the JSON Schema explained guide walks through type, properties, required, and the rest of the core vocabulary.

What does OpenAPI add?

When an OpenAPI contract changes after clients depend on it, use the guide to JSON API versioning mistakes to coordinate contract diffs, generated SDK tests, deprecation dates, and measured retirement.

An OpenAPI description can explain much more than the JSON body: endpoint paths, HTTP methods, parameters, response codes, request bodies, authentication schemes, and server details.

For example, OpenAPI can document GET /orders/{id} and describe its 200 response using a schema. JSON Schema by itself does not document the entire HTTP exchange. In OpenAPI, the schema sits under a media type, so the same endpoint can declare that its body is application/json (see the JSON Content-Type guide) and document a separate schema for its error responses:

paths:
  /orders/{id}:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

The important version difference

This is where mistakes tend to happen:

For example, an OpenAPI 3.0-style property might be:

website:
  type: string
  nullable: true

In an OpenAPI 3.1 schema, the JSON Schema way is:

website:
  type:
    - string
    - 'null'

That is not a universal find-and-replace instruction. Review the entire schema and validator compatibility during migration. The semantics of null itself, and how it differs from an absent key, are covered in the JSON null vs undefined guide.

Two more details matter when you move to 3.1. First, the top-level jsonSchemaDialect field declares the default dialect for every Schema Object in the document; when it is omitted, the OAS 3.1 base dialect applies, which is JSON Schema 2020-12 plus the OpenAPI keywords. Second, format values such as date-time, email, and uuid are annotations in JSON Schema unless the validator is configured to assert them, so do not assume a schema rejects a malformed timestamp just because format: date-time is present (the JSON date format guide explains why that field is a string in the first place).

A syntax validator cannot check your API contract

Suppose your API sends:

{"id":"1042","status":"paid","total":-20}

This is valid JSON syntax. But the schema above expects an integer id and a nonnegative total, so the data fails schema validation.

A tool such as JSON Prettifier is useful for identifying missing quotes, trailing commas and confusing nesting. For the contract itself, use a JSON Schema/OpenAPI validator that understands the dialect used by your project.

Which should you choose?

If your immediate problem is validating a configuration file, message payload or generic JSON document, JSON Schema may be sufficient. If you are documenting and tooling a REST API with endpoints, parameters and authentication, OpenAPI is usually the more complete description format.

They're not competing choices in every situation. You can use schemas to define the data portions of an OpenAPI contract and reuse compatible schema definitions across validation and documentation workflows—with attention to version compatibility. With OpenAPI 3.1 that reuse is straightforward, because a 2020-12 schema file can be referenced from components/schemas without translation; with 3.0 it usually means maintaining a trimmed copy.

If you're just learning syntax, start with What is JSON?. For API structures, see JSON in REST APIs. For malformed text, read common JSON errors.

Primary references for implementation decisions: JSON Schema specification and OpenAPI specification. Check the specification version relevant to your project.

The safe decision isn't to pick the schema format with the shortest file. Pick the one that describes your actual contract, then validate examples with tooling that understands the same version and dialect.

For the next review step, check these eight JSON Schema validation mistakes, including dialect mismatches, non-asserted formats, overlapping oneOf branches, and closed-schema composition.