How does OpenAPI 3.1 align with JSON Schema? #

One of the most significant changes introduced in OpenAPI 3.1 is its full alignment with the JSON Schema specification. In previous versions of OpenAPI, the Schema Object was described as an extended subset of JSON Schema with proprietary modifications — creating friction for developers who wanted to share schemas across different tools. OpenAPI 3.1 resolves this by adopting JSON Schema Draft 2020-12 as its schema vocabulary without modification. Understanding this alignment is essential for any team working with OpenAPI 3.1 and modern schema tooling.

A Brief History of the Divergence #

The OpenAPI Specification 2.0 (Swagger) was based on a subset of JSON Schema Draft 4, published in 2013. When OpenAPI 3.0 was released in 2017, it continued using an “extended subset” of JSON Schema Draft 4 — but with important modifications that made it incompatible with standard JSON Schema:

• nullable was introduced as a proprietary alternative to the JSON Schema approach of using type arrays.
• exclusiveMinimum and exclusiveMaximum were defined as booleans, overriding the JSON Schema Draft 6+ definition of them as numeric values.
• $ref did not allow sibling keywords, contrary to JSON Schema behavior.

This meant that OpenAPI 3.0 schemas could not be validated by standard JSON Schema validators, and JSON Schema tools could not consume OpenAPI schemas without a translation layer. OpenAPI 3.1 eliminates all these incompatibilities.

What is JSON Schema Draft 2020-12? #

JSON Schema Draft 2020-12 is the most recent stable version of the JSON Schema specification (also referred to as the “2020-12” draft). It defines a vocabulary for annotating and validating JSON documents and is supported by validators including:

• AJV (JavaScript) — the most widely used JSON Schema validator.
• jsonschema (Python)
• networknt/json-schema-validator (Java)
• Newtonsoft.Json.Schema (.NET)

By aligning with Draft 2020-12, OpenAPI 3.1 schemas can be validated by any of these tools out of the box — no translation, no forks, no custom extensions required.

Key JSON Schema Keywords Now Supported in OpenAPI 3.1 #

type as an Array #

In JSON Schema, type can be an array of type names, enabling a field to accept multiple types:

schema:
  type: [string, "null"]

This replaces OpenAPI 3.0’s proprietary nullable: true keyword, which has been removed in 3.1.

$schema #

OpenAPI 3.1 schema objects may include $schema to explicitly declare which JSON Schema dialect they use. This is particularly useful in documents that contain schemas targeting different dialects:

schema:
  $schema: "https://json-schema.org/draft/2020-12/schema"
  type: object

The openapi root object itself has a new jsonSchemaDialect field that sets the default $schema for all schemas in the document.

$id #

JSON Schema allows schemas to declare a canonical URI using $id. This enables schema identification and cross-schema referencing without relying on the document’s file path:

schema:
  $id: "https://api.example.com/schemas/user"
  type: object

This was not previously supported in OpenAPI.

$dynamicRef and $dynamicAnchor #

Introduced in Draft 2020-12, these keywords enable recursive and polymorphic schemas with late binding — powerful tools for describing tree structures or extensible data models without circular $ref issues:

schema:
  $dynamicAnchor: node
  type: object
  properties:
    children:
      type: array
      items:
        $dynamicRef: "#node"

unevaluatedProperties and unevaluatedItems #

These keywords provide precise control over additional properties and array items that are not covered by sibling schema keywords like properties or items. They enable stricter, closed schemas:

schema:
  type: object
  properties:
    name:
      type: string
  unevaluatedProperties: false

Unlike additionalProperties, unevaluatedProperties is aware of properties defined across allOf, anyOf, and oneOf branches — making it significantly more powerful for complex composed schemas.

const #

The const keyword restricts a field to a single exact value:

schema:
  type: string
  const: "enabled"

This replaces the common pattern of using enum with a single element.

prefixItems #

In Draft 2020-12, tuple validation uses prefixItems (an array of schemas) instead of the older items array syntax:

schema:
  type: array
  prefixItems:
    - type: string
    - type: number
  items: false

if / then / else #

Conditional schema application — introduced in Draft 7 and fully supported in 2020-12 — is now valid in OpenAPI 3.1 schemas:

schema:
  if:
    properties:
      type:
        const: "business"
  then:
    required: [taxId]
  else:
    required: [personalId]

$ref Sibling Keywords #

In OpenAPI 3.0, keywords alongside a $ref were silently ignored. In OpenAPI 3.1, following JSON Schema behavior, sibling keywords are merged with the referenced schema:

schema:
  $ref: "#/components/schemas/BaseUser"
  description: "A user with administrator privileges"
  properties:
    adminLevel:
      type: integer

This enables precise, local overrides without duplicating entire schema definitions.

The jsonSchemaDialect Field #

OpenAPI 3.1 adds a new top-level field jsonSchemaDialect to the root document object, allowing API designers to set the default JSON Schema dialect for all schema objects in the document:

openapi: 3.1.0
jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema

If omitted, the default is the OpenAPI 3.1 schema dialect, which is a superset of JSON Schema 2020-12 with OpenAPI-specific vocabulary additions.

Removed OpenAPI-Specific Schema Modifications #

OpenAPI 3.1 removes keywords that existed in 3.0 due to the JSON Schema divergence:

• nullable — replaced by type arrays: type: [string, "null"].
• Boolean exclusiveMinimum/exclusiveMaximum — replaced by numeric exclusive bounds from Draft 7+.

Teams migrating from 3.0 to 3.1 must update these patterns throughout their schemas.

Impact on Tooling #

Full JSON Schema alignment means OpenAPI 3.1 schemas are natively usable with the broader JSON Schema ecosystem:

• Validation libraries — AJV, jsonschema, and others can validate data against OpenAPI 3.1 schemas with no OpenAPI-specific adapters needed.
• Schema registries — schemas can be published to registries like Confluent Schema Registry or shared across services.
• Code generators — tools like quicktype that generate types from JSON Schema can now work directly with OpenAPI 3.1 schemas.
• Documentation tools — Redoc and Stoplight Elements render 3.1-specific keywords properly.

Conclusion #

OpenAPI 3.1’s full alignment with JSON Schema Draft 2020-12 is a landmark improvement that resolves years of friction between the OpenAPI and JSON Schema ecosystems. By adopting the complete JSON Schema vocabulary — including $id, $dynamicRef, unevaluatedProperties, const, and conditional schemas — OpenAPI 3.1 becomes a first-class citizen of the broader schema tooling world. For teams building APIs, this means less translation, broader tool compatibility, and richer schema expressiveness than any previous version of the OpenAPI Specification.

Last updated on April 29, 2026.