OpenAPI gets an update with JSON Schema compatibility, webhook support, and cosmetic fixes.

Just over a year after OAS 3.0.3’s release — and five months after OAS 3.1.0 RC1’s — OAS 3.1.0 has finally hit the airwaves. This is the OpenAPI Initiative’s newest major revision to the OAS 3.0 branch. Despite this, the specification’s developers want the upgrade to feel incremental for new users. Corporate users reliant on OAS should feel more comfortable with swift adoption. While semantic naming conventions dictate the jump to OAS 4.0, the leap would discourage quick embracement of critical changes.

While the consortium is always advancing development, releases tend to be spaced apart over months or years. Adopters should get comfortable with this latest build. Thankfully, there are plenty of updated goodies for developers to unpack. What exactly has changed?

Complete JSON Schema Compatibility

Changes under the JSON Schema umbrella headline this new OAS release. JSON is the default format for OpenAPI documents (aside from YAML), and has become immensely important for developers worldwide. Unfortunately, support shortcomings and iffy standardization have hampered the utility of JSON Schema and similar data structures. Schema extensions have been the products of numerous approaches.

OAS 3.1.0 solves many of these problems via 100% compatibility with JSON Schema’s latest draft (2020–12). This version emphasizes schema extension standardization. The inclusion of new vocabularies bolsters this standards-based focus — impacting processes like code creation, UI development, and documentation. Since OpenAPI itself champions standardized programming for modern APIs, this change is both philosophically and functionally relevant. The JSON Schema will also remain a useful guideline for validation.

Note: These schema vocabularies are now referred to as “schema dialects” within the release version.

File upload descriptions have been altered in lockstep with new JSON Schema developments. The OpenAPI Initiative warns that this may be a breaking change, even within the stable build. Overall, greater integration with JSON Schema constitutes an opportunity for enhanced behavior definition within the OAS. Accordingly, the addition of the jsonSchemaDialect top-level field facilitates default value declarations for Schema Objects.

Better Webhooks Descriptions

Many companies use webhooks to share data between applications. Many of these webhooks (like those used by Stripe and GitHub, for example) are developed in-house; however, they’re not always manageable on the corporate network.

This network is subject to occasional outages — as no ecosystem enjoys 100% uptime. Those leveraging intermediary, server-server webhooks must manage them remotely as needed. This is especially relevant in today’s climate. These webhooks are thus managed out of band. It’s equally important to account for these special Webhooks accordingly — as they deliver data and push events in unique ways.

OAS 3.1.0 introduces a new top-level element to describe out-of-band webhooks. The same goes for webhooks that are externally registered. Developers can describe each webhook’s parameters, purpose, and interactions beyond what’s automatically generated. APIs have enjoyed this functionality under the OAS for some time.

Descriptions may be long or short. Furthermore, some objects allow for summaries. Description-based changes were instituted to boost document clarity — while supplying greater context for each technology in question.

Say Hello to Standardized Identification

In the previous OAS version, license object identification for exposed APIs had two parts: a name and URL. These fields are both strings. The license name for each API was required, while any URLs to API licenses had to be in URL format. License objects were also extendable under the specification.

OAS 3.1.0 now supports API license identification via the standard SPDX identifier. The SPDX standard employs a License List, which catalogs full license names, identifiers, FSF freedom, and OSI approval. With that comes any noted license exceptions and shortened identifiers for your source code.

SPDX standardization also employs cleaner, machine-readable data files. Included URLs are canonical and permanent — so there’s no risk of using a bad link. The SPDX standard is living, which means certain components are subject to depreciation or replacement over time. This supported identification standard is backed by the Linux Foundation.

Easier Reusability

The PathItems object is now optional under OAS 3.1.0. Previously, some users complained that best practices weren’t clear surrounding external path storage or referencing. Additionally, the $ref field was insufficient for referencing and holding path items in components. The lack of a reusable component for PathItems meant that $ref properties had to point to external resources. This was sometimes tricky. It also made documentation less manageable.

Reusable PathItems are now describable in the components object. The benefit is simpler creation of reusable component libraries. Additionally, APIs using client security certificates may now have descriptions for enhanced transparency.

Miscellaneous Changes

As with any new release, there’s plenty of focus on cleanup. OAS 3.1.0 has worked to patch many nagging issues lingering in version 3.0.3 and earlier. Some links now have more accurate locations; accordingly, URIs and URLs enjoy a revamped relative reference resolution. Some Specification Extension prefixes have been reserved for OpenAPI Initiative definitions.

Lastly, a number of clarifications have been added surrounding parameter values, Reference Objects, documentation examples, descriptions, and nomenclature standards.

Overall, the latest update to OAS brings numerous quality-of-life changes to the party. The Initiative states that developer feedback played a key role in determining priorities and fixes. Users are encouraged to upgrade under the assurance that it won’t be a significant undertaking — nor require extensive reworkings.

For a deeper look at the new features in OAS 3.1.0, watch OpenAPI contributors Darrel Miller and Ron Ratovsky introduce the updates here: