DEV Community

Jeff
Jeff

Posted on Originally published at powerduck.com

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. 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"]
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)