OpenAPI 3.1 — New Features and Migration Guide

In this tutorial, you will learn about OpenAPI 3.1. We cover key concepts, practical examples, and best practices to help you master this topic.

OpenAPI 3.1 introduced full JSON Schema 2020-12 support, webhook definitions, improved examples format, and alignment with JSON Schema for better validation and tooling compatibility.

In this tutorial, you will learn the key differences between OpenAPI 3.0 and 3.1, how to migrate your specs, and how to take advantage of new features.

What You'll Learn

You will learn the major improvements in OpenAPI 3.1, how to migrate from 3.0 to 3.1, and how to use new features like Webhooks, full JSON Schema, and the new examples format.

Why It Matters

OpenAPI 3.1 is the current version and all new APIs should use it. It resolves limitations of 3.0, provides better JSON Schema alignment, and adds features like webhooks that were previously impossible to describe.

Real-World Use

DodaTech migrated all API specs from OpenAPI 3.0 to 3.1 in Q1 2026. The Migration enabled better schema validation, webhook documentation for event-driven features, and improved compatibility with modern tooling.

flowchart LR
  A[OpenAPI 3.0] --> B[Migration]
  B --> C[OpenAPI 3.1]
  C --> D[Full JSON Schema]
  C --> E[Webhooks]
  C --> F[New Examples]
  B:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Key Changes in OpenAPI 3.1

Full JSON Schema Support

OpenAPI 3.0 used a subset of JSON Schema draft 07. OpenAPI 3.1 uses full JSON Schema 2020-12. This means you can use all JSON Schema keywords including const, if/then/else, and propertyNames.

# OpenAPI 3.0: limited JSON Schema
type: object
properties:
  name:
    type: string
    minLength: 1

# OpenAPI 3.1: full JSON Schema
type: object
properties:
  name:
    type: string
    minLength: 1
    maxLength: 100
    const: "default"  # new in 3.1
if:
  properties:
    type:
      const: "premium"
then:
  properties:
    maxStorage:
      type: integer
      minimum: 100

Webhooks Support

OpenAPI 3.1 adds a top-level webhooks section that describes events the API can emit to registered callbacks.

openapi: 3.1.0
info:
  title: DodaTech Webhooks
  version: 1.0.0
webhooks:
  user.created:
    post:
      summary: Fired when a new user is created
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                name:
                  type: string
                email:
                  type: string
      responses:
        "202":
          description: Webhook accepted
  document.updated:
    post:
      summary: Fired when a document is modified
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DocumentEvent"
      responses:
        "202":
          description: Webhook accepted

New Examples Format

OpenAPI 3.1 aligns examples with JSON Schema 2020-12, supporting multiple named examples.

# OpenAPI 3.0: examples as array
schema:
  type: object
  properties:
    name:
      type: string
      example: "Alice"

# OpenAPI 3.1: named examples
Schema:
  type: object
  properties:
    name:
      type: string
      examples:
        - "Alice"
        - "Bob"
        - "Charlie"

# Request body examples in 3.1
requestBody:
  content:
    application/json:
      schema:
        $ref: "#/components/schemas/CreateUser"
      examples:
        basic:
          summary: Minimal user creation
          value:
            name: "Alice"
            email: "alice@example.com"
        admin:
          summary: Admin user creation
          value:
            name: "Bob"
            email: "bob@example.com"
            role: "admin"

Webhook Interaction with Paths

In OpenAPI 3.1, webhooks can reference paths within the paths section, allowing reusability of existing operation definitions.

paths:
  /users:
    post:
      operationId: createUser
      requestBody:
        $ref: "#/components/requestBodies/CreateUser"
      responses:
        "201":
          description: User created

webhooks:
  user.created:
    post:
      $ref: "#/paths/~1users/post"

Migration from 3.0 to 3.1

Update the openapi field to 3.1.0. Review nullable attributes and convert to JSON Schema null type or remove nullable. Review examples format and update to named examples. Add webhooks if needed. Update tooling to versions that support 3.1.

# Before (3.0)
openapi: "3.0.3"
components:
  schemas:
    User:
      type: object
      properties:
        name:
          type: string
          nullable: true
        email:
          type: string

# After (3.1)
openapi: 3.1.0
components:
  schemas:
    User:
      type: object
      properties:
        name:
          type:
            - string
            - "null"
        email:
          type: string

Common Mistakes

1. Keeping OpenAPI 3.0 syntax in 3.1 — Using nullable: true instead of the JSON Schema type array. In 3.1, nullable is removed in favor of type: [string, "null"].

2. Not updating tooling — Using older versions of Swagger UI or codegen that do not support 3.1. Update all tools before migrating.

3. Ignoring webhooks — Continuing to document webhooks outside the spec. Use the webhooks section for proper documentation.

4. Breaking changes from 3.0 examples — The examples format changed. Review all examples during migration.

5. Not testing after migration — Assuming the spec works without validation. Run all tools and tests after migrating.

Practice Questions

1. What is the most significant change in OpenAPI 3.1?
2. How do you define webhooks in OpenAPI 3.1?
3. What happened to the nullable attribute in 3.1?
4. How do the examples differ between 3.0 and 3.1?
5. What should you check after migrating from 3.0 to 3.1?

Challenge

Take an existing OpenAPI 3.0 spec and migrate it to 3.1. Update the openapi version, convert nullable attributes, update examples format, add a webhook for a resource creation event, and validate the migrated spec with the latest tooling.

FAQ

Mini Project

Create a migration guide for your organization to move from OpenAPI 3.0 to 3.1. Include a checklist of changes, tool updates needed, testing steps, and a rollback plan. Write a script that automates the migration of nullable and examples fields.

What's Next

In the next lesson, you will learn the complete structure of an OpenAPI document in detail.