OpenAPI 3.1 - The Gnarly Bits

Though obviously support in tooling has taken a little while to begin to appear, both for commercial and Open-Source offerings, there are already a number of resources available to help you get to grips with the latest version of the OpenAPI specification (OAS), whether you are entirely new to it, or an older hand looking to focus on the new features.

Lorna Mitchell, who championed the new webhooks feature, has a range of information available: a blog post, a video and associated slides.

Phil Sturgeon, who along with Ben Hutton and Henry Andrews from the JSON Schema community, helped drive the push to full JSON Schema Draft 2020-12 compliance, has written a blog post for the official OpenAPIs.org website on how to transition your OAS documents from v3.0.x to v3.1.0.

My fellow OpenAPI Initiative TSC members Ron Ratovsky and Darrel Miller presented a webinar on what's new in v3.1.

My fellow Postman colleague Arnaud Lauret (the API Handyman) gave a talk at the API Specifications Conference (ASC) in 2022 entitled OpenAPI 3.x Does What Swagger 2.0 Don’t.

Last but not least, the OpenAPI Initiative now has an official getting started guide.

So, with all that going on, is there anything much else to add?

Indeed there is, so let's take a top-down stroll through the OpenAPI specification, to focus on the details of what has changed.

Top-Level changes

As part of this release, we have decided to not follow SemVer anymore, and as such allow ourselves to introduce minor, but breaking changes. These changes are documented as part of the release notes.

Additions

• Introduced a new top-level field - webhooks. This allows describing out-of-band registered webhooks that are available as part of the API.
• The Info Object has a new summary field.
• The License Object now has a new identifier field for SPDX license codes.
• The Components Object now has a new entry pathItems, to allow for reusable Path Item Objects to be defined within a OpenAPI document.

Extended Functionality

• Updated primitive types to be based on JSON Schema Specification Draft 2020-12. This now includes type "null".
• Lifted the restriction of allowing Request Body only in HTTP methods where the HTTP 1.1 specification RFC9110 has explicitly defined semantics. While now allowed for other methods, this use is still not recommended.
• Added support for the object type for spaceDelimited and pipeDelimited style values.
• The Encoding Object now supports style, explode and allowReserved for the multipart/form-data media type as well.
• To enable better webhooks support, expressions in the Callback Object can now also reference Path Item Objects.
• When using the Reference Object, summary and description fields can now be overridden. This is the default behaviour, tooling may optionally allow merging or appending the text.
• The Schema Object is now fully compliant with JSON Schema draft 2020-12 (see JSON Schema Core and JSON Schema Validation). See also, Breaking Changes.
• The $ref keyword within Schema Objects can now contain relative JSON Pointers.
• The Discriminator Object can now be extended with Specification Extensions, correcting an oversight in version 3.0.
• Added support for mutual TLS (mutualTLS) as a security scheme type.
• Security requirements (such as for API keys) can now define an array of roles that are required for execution (and not only scopes for OAuth 2.0 security schemes).
• Added the jsonSchemaDialect top-level field to allow the definition of a default $schema value for Schema Objects. This allows any past or future version of JSON Schema to be used in your OAS documents, provided that tools support them.

Changes

• An OpenAPI Document now requires at least one of paths, components or webhooks to exist at the top level. While previous versions required paths, now a valid OpenAPI Document can describe only webhooks, or even only reusable components. Thus, an OpenAPI Document no longer necessarily describes an API.
• Anywhere in the 3.0 Specification that had a type of Schema Object | Reference Object has been replaced to be Schema Object only. With the move to full JSON Schema support, $ref is inherently part of the Schema Object and has its own defined behavior.
• Extensions prefixed with x-oas- and x-oai- are now reserved for the OpenAPI Initiative.
• The format keyword is now not validated by default. It is treated as an annotation. Tooling may allow opt-in validation on a best-case basis.
• The allowEmpty property on parameters is now deprecated as it had confusing and less-than-useful behaviour.

Breaking changes

• The specification versioning no longer follows SemVer.
• The nullable keyword has been removed from the Schema Object ("null" can be used as a type value).
• exclusiveMaximum and exclusiveMinimum do not accept boolean values (following JSON Schema). They are independent keywords which take a number.
• Due to the compliance with JSON Schema, there is no longer interaction between required and readOnly/writeOnly in relation to requests and responses.
• format (whether byte, binary, or base64) is no longer used to describe file payloads. As part of JSON Schema compliance, now contentEncoding and contentMediaType can be used to control this.
• The Server Object Variable's enum array now MUST not be empty (changed from SHOULD).
• The Server Object Variable's default property now MUST exist in the enum values, if such values are defined (changed from SHOULD).
• responses are no longer required to be defined under the Operation Object.

Clarifications

• Reworded the definition of OpenAPI Document to reflect that a document no longer must describe paths, but can describe either paths, webhooks, components or any combination of these.
• Dropped the term "RESTful APIs" in favor of "HTTP APIs"
• Resolution of relative references has been redefined and clarified. Note there's a difference in resolution between Schema Object References and all others.
• Modification of examples to improve them and provide context for new fields and objects.
• It is now clarified what happens when path template expressions do not have a corresponding path parameter.
• Data types (and just primitive data types) now correspond to JSON Schema.
• A new section was added to address how to handle the $schema keyword (implicitly and explicitly).
• Updated some inline links to more accurate or secure locations.
• Path parameter values cannot contain the unescaped characters /, ? or #.
• Further explanation of where Reference Object and JSON Schema's reference should be used.
• Unified wording when values are URLs/URIs.
• Reworded Path Item's $ref to take into account reference and component changes.
• Minor text changes to improve consistency and readability.
• The description of the Reference Object has been updated to further clarify its behavior.
• Further updated Schema Object's description to take into account the latest draft, and the default use of https://spec.openapis.org/oas/3.1/dialect/base as the default OAS dialect.
• Reworded "Schema Vocabularies" to "Schema dialects"

Conclusion

I hope this guide proves helpful to those considering using OAS 3.1, and those migrating from earlier versions. As ever, let me know in the comments if anything is wrong, unclear or missing.

Why not get involved in the discussions around a tentative OpenAPI 4.0, codename 'Moonwalk'?