Though obviously support intooling 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 newwebhooks feature, has a range of information available: ablog post, avideo and associatedslides.

Phil Sturgeon, who along withBen Hutton andHenry Andrews from theJSON Schema community, helped drive the push to full JSON SchemaDraft 2020-12 compliance, has written ablog post for the officialOpenAPIs.org website on how to transition your OAS documents from v3.0.x to v3.1.0.

My fellow OpenAPI Initiative TSC membersRon Ratovsky andDarrel Miller presented a webinar onwhat's new in v3.1.

My fellowPostman colleagueArnaud Lauret (the API Handyman) gave a talk at theAPI Specifications Conference (ASC) in 2022 entitledOpenAPI 3.x Does What Swagger 2.0 Don’t.

Last but not least, the OpenAPI Initiative now has an officialgetting 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 therelease 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 forSPDX license codes.
• The Components Object now has a new entrypathItems, 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 specificationRFC9110 has explicitly defined semantics. While now allowed for other methods, this use is still not recommended.
• Added support for the object type forspaceDelimited andpipeDelimited style values.
• The Encoding Object now supportsstyle,explode andallowReserved for themultipart/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 anddescription 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 (seeJSON Schema Core andJSON Schema Validation). See also, Breaking Changes.
• The$ref keyword within Schema Objects can now containrelative 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 thejsonSchemaDialect 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 ofpaths,components orwebhooks to exist at the top level. While previous versions requiredpaths, now a valid OpenAPI Document can describe onlywebhooks, or even only reusablecomponents. 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 withx-oas- andx-oai- are now reserved for the OpenAPI Initiative.
• Theformat keyword is now not validated by default. It is treated as an annotation. Tooling may allow opt-in validation on a best-case basis.
• TheallowEmpty property onparameters is now deprecated as it had confusing and less-than-useful behaviour.

Breaking changes

• The specification versioning no longer follows SemVer.
• Thenullable keyword has been removed from the Schema Object ("null" can be used as a type value).
• exclusiveMaximum andexclusiveMinimum do not accept boolean values (following JSON Schema). They are independent keywords which take anumber.
• Due to the compliance with JSON Schema, there is no longer interaction betweenrequired andreadOnly/writeOnly in relation to requests and responses.
• format (whetherbyte,binary, orbase64) is no longer used to describe file payloads. As part of JSON Schema compliance, nowcontentEncoding andcontentMediaType can be used to control this.
• The Server Object Variable'senum array now MUST not be empty (changed from SHOULD).
• The Server Object Variable'sdefault property now MUST exist in theenum 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 describepaths, but can describe eitherpaths,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 ofhttps://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 thediscussions around a tentative OpenAPI 4.0, codename 'Moonwalk'?