OpenAPI 3.1.0 Compared to 3.0.3

If you work with API specifications, you've likely come across the OpenAPI Specification (OAS). OpenAPI 3.1.0 brought some important changes that directly impact how we define and consume API contracts. Whether you're a developer writing API specs or a QA working on automation, it's useful to understand what changed between 3.0.3 and 3.1.0 and why it matters.

Compare OpenAPI 3.1.0 vs 3.0.3

Here's a quick summary:

Feature	OpenAPI 3.0.3	OpenAPI 3.1.0
JSON Schema version	Partial (draft-04 like)	Full (Draft 2020-12)
$schema support	Not supported	Supported at top-level
Webhooks	Not supported	Supported via webhooks object
nullable	Supported (custom keyword)	Deprecated in favor of type union
example keyword	Limited	Fully supported in schemas
Server variable default	Required	Optional
$ref behavior	Restricted (no siblings)	Standard JSON Schema behavior

Let's walk through the key differences with examples and rationale.

1. JSON Schema Compatibility

OpenAPI 3.0.3 supported a partial and modified form of JSON Schema, which led to confusion and limitations in tooling. For example, custom keywords like nullable were not part of the JSON Schema specification, and features like conditional logic or reusable fragments were either unavailable or required workarounds.

OpenAPI 3.1.0 fixes this by fully aligning with JSON Schema Draft 2020-12. This change simplifies authoring and increases interoperability.

3.0.3 Example:

schema:
  type: string
  nullable: true

3.1.0 Example:

schema:
  type: ["string", "null"]

Impact: Advanced JSON Schema features are now available, and schemas are easier to validate using standard tools.

2. $schema Declaration at Root

OpenAPI 3.0.3 documents did not specify which JSON Schema version they were compatible with, making schema validation inconsistent across tools.

OpenAPI 3.1.0 introduces the $schema keyword at the root, which explicitly states the dialect being used. This is especially useful for tooling and validators.

3.1.0 Example:

$schema: "https://spec.openapis.org/oas/3.1.0"
openapi: 3.1.0
info:
  title: Sample API
  version: 1.0.0

Impact: Tools can now correctly interpret the specification, improving validation accuracy.

3. Webhooks Support

Previously, OpenAPI had no native way to describe how an API receives external calls, such as webhooks triggered by external systems.

OpenAPI 3.1.0 introduces a new webhooks object. This makes it possible to describe asynchronous and event-driven APIs more completely.

3.1.0 Example:

webhooks:
  newPet:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
      responses:
        '200':
          description: Webhook received

Impact: You can now document webhook endpoints directly in the spec.

4. Server Variable default Is Optional

In 3.0.3, server variables required a default value, even if it didn’t make sense in the context. This added unnecessary constraints when defining environments.

3.1.0 changes this. default is now optional, matching JSON Schema behavior and making specs more flexible.

3.0.3 Example:

variables:
  env:
    enum:
      - dev
      - prod
    default: dev

3.1.0 Example:

variables:
  env:
    enum:
      - dev
      - prod

Impact: Less boilerplate when a default is not meaningful.

5. nullable Deprecated

The nullable keyword was a custom OpenAPI extension in 3.0.3, which caused confusion when working with JSON Schema tools.

In 3.1.0, this is replaced with the standard JSON Schema approach using union types.

Before (3.0.3):

schema:
  type: string
  nullable: true

After (3.1.0):

schema:
  type: ["string", "null"]

Impact: Aligns with JSON Schema and improves compatibility with schema validators.

6. Examples Are Now First-Class JSON Schema Keywords

In 3.0.3, examples could only be used in certain parts of the spec. They were not allowed directly inside JSON Schema definitions.

OpenAPI 3.1.0 fixes this. Now you can embed example inside any JSON Schema object.

3.1.0 Example:

schema:
  type: object
  properties:
    name:
      type: string
      example: "Max"

Impact: Makes specs more expressive and readable.

7. Better $ref Behavior

In OpenAPI 3.0.3, $ref could not be used with sibling keywords like description or example. This often forced workarounds using allOf.

OpenAPI 3.1.0 aligns $ref behavior with JSON Schema, removing those restrictions.

Impact: You can now use $ref more naturally and expressively in your specs.

Final Thoughts

If you're starting a new project, prefer 3.1.0. The full JSON Schema support alone makes it worth the upgrade. However, if you're working with tools that don’t yet support 3.1.0, you may want to stick with 3.0.3 for now.