SchemaInterface
Back to Guides

OpenAPI 3.1 vs JSON Schema: The Convergence

Published: Oct 12, 2023 | Reading Time: 8 min

For years, API developers lived with a frustrating dichotomy: OpenAPI 3.0 used a subset/superset of JSON Schema Draft 4, meaning tools designed for one often failed on the other. With OpenAPI 3.1, this divergence has officially ended.

The Historical Problem

Prior to version 3.1, OpenAPI defined its own Schema Object. While heavily inspired by JSON Schema, it introduced critical incompatibilities:

  • Type arrays: OpenAPI 3.0 required nullable: true instead of type: ["string", "null"].
  • Exclusive limits: OpenAPI 3.0 used boolean flags (exclusiveMinimum: true) alongside limits, whereas JSON Schema updated to numeric exclusive limits.
  • Missing keywords: Keywords like const, if/then/else, and dependentRequired were absent from OpenAPI 3.0.

The OpenAPI 3.1 Resolution

OpenAPI 3.1 declares that its Schema Object is fully compliant with JSON Schema Draft 2020-12. This means:

1. Type Arrays are Native

You can now define nullable strings precisely as the JSON Schema spec dictates, without custom vocabulary.

"address": {
  "type": ["string", "null"]
}

Migration Path for Infrastructure Teams

If you maintain API Gateways or code generators, migrating to 3.1 requires upgrading your underlying parsing libraries.

  1. Update your validator to support Draft 2020-12. (SchemaInterface supports this out of the box via our Enterprise CLI).
  2. Remove internal pre-processing steps that stripped nullable keywords.
  3. Adopt the new $id resolution mechanics for internal schema references.

Ready to validate your specs?

Drop your OpenAPI 3.1 schemas into our strict evaluation engine.

Open Validator