What’s New in OpenAPI 3.1.0? Key Features and Improvements Explained

At the start of the year, major vendors released new products, including Spring Boot 2.4.3 and the OpenAPI Specification 3.1.0.

OpenAPI 3.1.0, built on the 3.1.0‑rc1 release, brings several breakthrough optimizations.

New Additions

Added the jsonSchemaDialect top‑level field to allow defining a default $schema value for schema objects.

Updates

Updated several links to point to more accurate locations.

Updated JSON Schema support to the latest 2020‑12 draft.

Modified relative reference parsing for uri and url fields.

Revised file‑upload descriptions to consider new JSON Schema capabilities, introducing significant changes.

Retained the x‑oai and x‑oas prefix extensions defined by OpenAPI.

Explanations

Path parameter values cannot contain unescaped characters /, ?, or #.

Further explanation of where to use reference objects and JSON Schema references.

Unified usage when values are URLs/URIs.

Rewrote path item $ref handling to account for reference and component changes.

Corrected several examples.

Minor text changes to improve consistency and readability.

Updated the description of reference objects to clarify their behavior.

Enhanced the description of Schema objects to reflect the latest draft and default to https://spec.openapi.org/oas/3.1/dialect/base as the OAS dialect.

Renamed “Schema Vocabularies” to “Schema dialects”.

For the full release details, see OpenAPI Specification 3.1.0 on GitHub .