OpenAPI 3.1 New Features and JSON Schema Alignment

OpenAPI 3.1 New Features

OpenAPI 3.1 is a significant update that aligns the specification with JSON Schema 2020-12. This brings powerful schema features and simplifies the relationship between OpenAPI and JSON Schema.

Full JSON Schema Compatibility

The biggest change: OpenAPI 3.1 schemas are valid JSON Schema 2020-12:

# OpenAPI 3.0 (custom nullable)
name:
  type: string
  nullable: true

# OpenAPI 3.1 (JSON Schema standard)
name:
  type: [string, "null"]

Type Arrays

Replace nullable with type arrays:

# 3.0
age:
  type: integer
  nullable: true

# 3.1
age:
  type: [integer, "null"]

# Multiple types
value:
  type: [string, integer]

The const Keyword

Fixed values without enum:

# 3.0
type:
  type: string
  enum: [user]

# 3.1
type:
  const: user

Webhooks Section

New top-level section for webhook definitions:

openapi: "3.1.0"
webhooks:
  newOrder:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Order"
      responses:
        "200":
          description: OK

Conditional Schemas (if/then/else)

Address:
  type: object
  properties:
    country:
      type: string
    state:
      type: string
    province:
      type: string
  if:
    properties:
      country:
        const: US
  then:
    required: [state]
  else:
    required: [province]

$ref with Siblings

In 3.0, $ref could not have sibling keywords. In 3.1:

# 3.0 — not valid
property:
  $ref: "#/components/schemas/Base"
  description: Override description

# 3.1 — valid
property:
  $ref: "#/components/schemas/Base"
  description: Override description

contentMediaType and contentEncoding

Document Base64-encoded properties:

avatar:
  type: string
  contentMediaType: image/png
  contentEncoding: base64

$dynamicRef for Extensibility

For advanced schema extensibility:

$defs:
  node:
    type: object
    properties:
      value:
        type: string
      children:
        type: array
        items:
          $dynamicRef: "#node"

Migration from 3.0

Key changes to make:

1. Change openapi: "3.0.x" to openapi: "3.1.0"
2. Replace nullable: true with type: [original_type, "null"]
3. Replace single-value enum with const
4. Move webhook callbacks to the new webhooks section
5. Add $ref siblings where needed