# OpenAPI JSON Schema Differences

Quick answer: OpenAPI does not run on the full JSON Schema standard. It borrows JSON Schema's structure and changes a few keywords, so some valid JSON Schema constructs fail in OpenAPI and vice versa. OpenAPI 3.0 uses an extended subset of an early draft with its own rules, while 3.1 aligns with JSON Schema 2020-12; the differences that bite teams are null handling, numeric bounds, `$ref` siblings, and the `type` field.

## Why the two are not identical

JSON Schema is its own specification, released as drafts such as Draft 7 and 2020-12. OpenAPI reuses that vocabulary for request and response bodies but keeps control of a few keywords so the schema can drive documentation and code generation. The result is a moving target: 3.0 sits on an extended subset of the Wright Draft 00 shape rather than a published draft, and 3.1 closes most of the gap with 2020-12.

This matters because a plain JSON Schema validator and an OpenAPI-aware validator do not read the same document, a theme across the broader [OpenAPI guide hub](https://www.powerduck.com/blog/openapi-guide-hub/). A keyword one tool accepts can make the other reject the file or ignore a rule.

## The differences that matter

| Area | OpenAPI 3.0 | OpenAPI 3.1 / JSON Schema 2020-12 |
|---|---|---|
| Null value | `nullable: true` | `type` array including `"null"` |
| `type` field | A single string only | A string or an array of strings |
| Exclusive bounds | Boolean next to `minimum` | A number standing on its own |
| Keywords next to `$ref` | Ignored | Honored |
| Examples | `example` for one value | `example` plus the standard `examples` array |
| Modern keywords | No `$anchor`, `$dynamicRef`, or `unevaluatedProperties` | Supported |
| OpenAPI extras | `discriminator`, `xml`, `readOnly`, `writeOnly` | Kept alongside the standard keywords |

The OpenAPI-specific keywords are why the two specs never match perfectly. `discriminator` and `xml` describe API and serialization concerns plain JSON Schema has no opinion about, so they survive even in 3.1.

## How the same rule looks in each version

A nullable field changes the most between versions. In 3.0 you set a boolean alongside the type; in 3.1 you list null as an allowed type.

```yaml
# OpenAPI 3.0
price:
  type: number
  nullable: true

# OpenAPI 3.1
price:
  type: [number, "null"]
```

Exclusive numeric bounds follow the same pattern. The 3.0 boolean works only with `minimum` or `maximum`, while 3.1 takes the bound as a number.

```yaml
# OpenAPI 3.0
minimum: 0
exclusiveMinimum: true

# OpenAPI 3.1
exclusiveMinimum: 0
```

The `$ref` rule is less visible but causes real confusion. In 3.0, a `$ref` resolves to the target and sibling keywords, including `description`, are not read. In 3.1 those siblings are honored, so the reference can carry its own description.

## What this means for tooling and upgrades

A standard JSON Schema validator will not understand `nullable` and may flag a 3.0 document, just as an OpenAPI 3.0 tool rejects a 3.1 file using a `type` array. Match the validator to the document version instead of assuming the two are interchangeable.

When moving from 3.0 to 3.1, plan three edits: replace every `nullable` with a null type, convert boolean bounds into numbers, and review references that relied on siblings being ignored. Generators map these keywords to optional and nullable types, so a missed conversion yields a model that no longer matches the wire format.

After importing the spec into Powerduck, open the data models to confirm how each keyword resolves and send a request that violates a constraint, so the documented schema and the server's validation tell the same story.

## Common mistakes

- **Using a `type` array in 3.0.** The 3.0 `type` field accepts one string; multi-type expressions belong to 3.1.
- **Expecting a `$ref` sibling to work in 3.0.** A `description` next to the reference is ignored until the document moves to 3.1.
- **Mixing null styles.** Writing both `nullable: true` and a null type doubles the rule and confuses generators.
- **Number bounds in the wrong version.** A numeric `exclusiveMinimum` is a 3.1 form; 3.0 expects a boolean paired with `minimum`.
- **Validating 3.0 with a generic JSON Schema tool.** Use an OpenAPI-aware validator so the added keywords are recognized.

## Frequently asked questions

**Which JSON Schema version does OpenAPI use?** OpenAPI 3.0 uses an extended subset modeled on Wright Draft 00, not a complete published draft. OpenAPI 3.1 aligns with JSON Schema 2020-12.

**Is `nullable` still supported?** Only in 3.0. In 3.1 it is removed; express nullability by including `"null"` in the `type` array.

**Why does my `$ref` description not appear?** In 3.0, `$ref` siblings are ignored. Upgrade to 3.1 or move the description onto the referenced schema.

**Can a standard JSON Schema validator check an OpenAPI file?** It can check parts of a 3.1 document, but it will not recognize OpenAPI keywords and will misread 3.0 constructs like `nullable`. Use a validator for the OpenAPI version you ship.

## The bottom line

Pick the document version first and let every validator and generator follow it. In 3.0, stay inside its single-type, boolean-bound, `$ref`-only rules; in 3.1, use the standard 2020-12 forms. Treating the two specs as the same produces schemas that validate in one tool and break in the next.
