After over a year of development, the Open API Initiative has announced that it will release OpenAPI Specification (OAS) v3.0.0 final in mid-July 2017. The release will follow an open comment period that ends on June 30.
The release has been closely followed by the API community, with developers and industry leaders being vocal of the features they are most excited about. Key features of OAS 3.0 that are garnering the most attention include:
- Components
- Support for multiple hosts
- Content negotiation with the new Content property
- Support for callbacks and webhooks
- Hints at hypermedia with the Links object
- Improved support for JSON Schema’s anyOf, allOf, and not functions
As the specification reaches 3.0, open-source communities and vendors are working to provide forward compatibility in their OAS tooling. Speaking with InfoQ last year, Tony Tam, creator of the Swagger description language on which OAS is based, warned of the breaking changes to come:
Many tooling vendors will be able to support both 2.0 and 3.0 specifications with updated tooling, but 2.0 tooling will almost certainly not work with 3.0 specifications. We expect—and encourage a better forward compatibility across tooling implementations. We will ensure that any subsequent updates to the 3.0 specification be treated as non-breaking to earn a 3.x version number.
Darrel Miller, member of the OAS Technical Developer Community (TDC), which is a six-person group responsible for providing the technical direction for the spec, spoke with InfoQ about the major challenges the TDC faced in preparing for this release: time and prioritization. "We are fortunate the there is an enthusiastic community who volunteered many hours of additional effort to help the spec get to where it is," he said. "We have limited time and capacity and we want to strike a balance between adding features and maintaining simplicity. We all have seen what happens to specs that get too complicated. However, for every bit of complexity there was always some user who really needed that bit of functionality. Saying no is rarely received well, but it is just as important as saying yes to new features."
While no concrete plans for the next version have yet been made, the TDC is actively discussing what may be in store for a future release. In a workshop at Gluecon in May that covered the major changes in 3.0, Miller also introduced features that have experimental support: reusable groups, alternative schemas, operation versioning, and dynamic enums. According to Miller, reusing groups of objects is a high priority for a future update, and alternative schemas have been a popular request, although this poses nontrivial challenges to ensuring users have good and consistent experiences with tooling. On the topic of the next release, he says, "I expect that the wait for whatever the next version is, will be much shorter than the time it has taken to get to V3."