OpenAPI 3.1: A Significant Upgrade for API Specification

OpenAPI 3.1 was one of the most anticipated releases in the API specification world. After years of OpenAPI diverging from the JSON Schema standard it was based on, version 3.1 finally brings full alignment with JSON Schema 2020-12. This isn't just a technical detail — it has real implications for tooling, validation, and how you design APIs day-to-day.

Full JSON Schema Alignment

Before 3.1, OpenAPI used a "JSON Schema subset" with several additions and subtractions that made it incompatible with standard JSON Schema validators. This caused headaches for tooling authors and meant you often had to maintain separate schemas for your API spec and your data validation logic.

With 3.1, OpenAPI schemas are valid JSON Schema. This means:

  • You can use any compliant JSON Schema validator directly on your OpenAPI schemas.
  • Tooling built for JSON Schema now works with OpenAPI specs without custom adapters.
  • Features like unevaluatedProperties, prefixItems, and $dynamicRef are now available.

Webhooks Support

OpenAPI 3.1 introduces a top-level webhooks field alongside the existing paths field. Previously, developers had to use the callbacks field or document webhooks in prose — a clunky workaround.

Now you can formally describe the events your API emits:

webhooks:
  newOrder:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'

This makes webhook contracts machine-readable and enables code generation for webhook consumers — a long-requested feature.

Nullable Is Gone (Mostly)

One of the more disruptive changes: the nullable: true keyword is deprecated. Instead, you use the standard JSON Schema approach of combining types:

# Old (3.0)
type: string
nullable: true

# New (3.1)
type: [string, "null"]

This is more semantically correct and aligns with how JSON Schema handles nullability, but it requires updates to your existing specs and any tooling that relied on nullable.

License and Info Object Improvements

The info object now supports a summary field (a short description alongside the longer description). The license object gains an identifier field for SPDX license identifiers, useful for open APIs that need to surface their license clearly.

Shared Schemas via $schema

You can now declare the JSON Schema dialect at the document or individual schema level using the $schema keyword. This gives validators explicit guidance on which dialect to use when validating schemas within the document.

What This Means for Your Workflow

  1. Check your tooling: Not all tools support 3.1 yet. Before migrating, verify that your code generators, validators, and API gateways have updated support.
  2. Update nullable fields: Run a search for nullable: true in your specs and migrate to the new union type syntax.
  3. Document your webhooks properly: Take the opportunity to move webhook documentation from prose into the formal webhooks field.
  4. Leverage JSON Schema libraries: You can now validate API payloads using the same schemas in your spec, reducing duplication.

Adoption Timeline

Major tooling vendors — including Swagger UI, Redoc, and various code generators — have been rolling out 3.1 support. If you're starting a new API project today, 3.1 is the right choice. For existing APIs, migration is worthwhile but should be planned carefully to avoid breaking tooling integrations mid-project.

OpenAPI 3.1 is a mature, well-considered release that resolves long-standing pain points. The JSON Schema alignment alone makes it worth the upgrade for teams who care about rigorous API design.