Introduction
The OpenAPI Initiative (OAI), a consortium of forward-looking industry experts who focus on standardizing how APIs are categorized and described, released the OpenAPI Specification 3.1.0 in February. This new version introduces better support for webhooks and adds 100% compatibility with the latest draft (2020-12) of JSON Schema.
Complete information on the OpenAPI Specification (OAS) is available for immediate access here: https://spec.openapis.org/oas/v3.1.0 It includes Definitions, Specifications including Schema Objects, and much more.
Also, the OAI sponsored the creation of new documentation to make it easier to understand the structure of the specification and its benefits. It is available here: https://oai.github.io/Documentation. It is intended for HTTP-based API designers and writers wishing to benefit from having their API formalized in an OpenAPI Description document.
What is the OpenAPI Specification?
The OAS is the industry standard for describing modern APIs. It defines a standard, and programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic.
The OAS is used by organizations worldwide, including Atlassian, Bloomberg, eBay, Google, IBM, Microsoft, Oracle, Postman, SAP, SmartBear, Vonage, and many more.
JSON Schema Now Supported
The Schema Object defines everything inside the `schema` keyword in OpenAPI. Previously, this was loosely based on JSON Schema and referred to as a “subset superset” because it added some things and removed other things from JSON Schema. The OpenAPI and JSON Schema communities worked together to align the specifications to align tooling and approach.
Supporting modern JSON Schema is a significant step forward.
“The mismatch between OpenAPI JSON Schema-like structures and JSON Schema itself has long been a problem for users and implementers. Full alignment of OpenAPI 3.1.0 with JSON Schema draft 2020-12 will not only save users much pain but also ushers in a new standardized approach to schema extensions,” said Ben Hutton, JSON Schema project lead.
“We’ve spent the last few years (and release) making sure we can clearly hear and understand issues the community faces. With our time-limited volunteer-based effort, not only have we fixed many pain points and added new features, but JSON Schema vocabularies allows for standards to be defined which cater for use cases beyond validation, such as the generation of code, UI, and documentation.”
Major Changes in OpenAPI Specification 3.1.0
- JSON Schema vocabularies alignment
- New top-level element for describing Webhooks that are registered and managed out of band
- Support for identifying API licenses using the standard SPDX identifier
- PathItems object is now optional to make it simpler to create reusable libraries of components. Reusable PathItems can be described in the components object. There is also support for describing APIs secured using client certificates.
Full OAS 3.1.0 details are available here: https://spec.openapis.org/oas/v3.1.0 The new documentation is available here: https://oai.github.io/Documentation/
Get Involved in the OAI
To learn more about participating in the evolution of the OAS: https://www.openapis.org/participate/how-to-contribute
- Become a Member
- OpenAPI Specification Twitter
- OpenAPI Specification GitHub – Get started immediately!
- Share your OpenAPI Spec v3 Implementations
Conclusion
In order to achieve the impressive goal of full compatibility with modern JSON Schema, the OAS underwent important updates that make things a lot easier for tooling maintainers, as they no longer need to try and guess what draft a schema is by looking at where it is referenced from. Just this makes implementation of OAS 3.1.0 important to evaluate and strongly consider.
