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. 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.
# 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.
# 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
typearray in 3.0. The 3.0typefield accepts one string; multi-type expressions belong to 3.1. - Expecting a
$refsibling to work in 3.0. Adescriptionnext to the reference is ignored until the document moves to 3.1. - Mixing null styles. Writing both
nullable: trueand a null type doubles the rule and confuses generators. - Number bounds in the wrong version. A numeric
exclusiveMinimumis a 3.1 form; 3.0 expects a boolean paired withminimum. - 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.
Comments
Join the discussionNo comments yet. Be the first to comment.

