API Specifications Update for September 1st, 2021

The evolution of OpenAPI, AsyncAPI, and JSON Schema is important to what I do at Postman, but also to the wider API space. I find it helpful to understand what is happening across each of the API specification communities, and I wanted to also find a way to share what I am seeing with everyone else. Each week I spend time to create a single digest of what is happening, without having to do all the work I am doing each week. While I am sure there is much more going on that I am not tuned into, here is what I see as the snapshot of what I see happening across the API specifications.

Recent Meetings

Upcoming Meetings

Interesting Issues

  • Proposal to be able to name channel item object · Issue #614 · asyncapi/spec - I'm trying to generate websocket code from AsyncAPI docs. I don't know if this is the case for other protocols too, but for websocket subscribe and publish is performed on the same connection. Currently only Operations (publish and subscribe) are nameable using operationId. For sockets it makes no sense to open 2 separate connection, one for publishing one for subscribing.
  • Channel Item Object `$ref` field resolution rules · Issue #612 · asyncapi/spec - Allows for an external definition of this channel item. The referenced structure MUST be in the format of a Channel Item Object. If there are conflicts between the referenced definition and this Channel Item's definition, the behavior is undefined.
  • JSON Hyper-Schema Needs Schema Version Parity · Issue #1120 · json-schema-org/json-schema-spec - In release 2020-12, JSON Schema released new draft schemas without updating Hyper-Schema. As a result, Hyper-Schema's most recent drafts are associated with 2019-09. Given the differences between 2019-09 and 2020-12, as well as differences in implementations, the lack of schema parity for Hyper-Schema discourages its adoption. I propose that even without feature changes to Hyper-Schema, its meta-schemas and related materials should continue to be updated and released as part of the JSON Schema cohort of specifications.
  • Support for unevaluatedProperties in OAS 3.1+? · Issue #2691 - The latest (draft 2020-12) version of JSON Schema supports the unevaluatedProperties vocabulary (see here). This is quite a useful feature, and facilitates stricter validation while composing properties from multiple sub-schemas (using e.g. allOf) than would otherwise possible.
  • OpenAPI 3.1 examples not validating through AJV using OpenAPI 3.1 spec · Issue #2689 - There is a lot of JavaScript tooling that uses AJV to validate OpenAPI specs. None of it seems to support 3.1, which is really unfortunate. I was trying to remedy the situation, but failed miserably.
  • OpenAPI bundling proposal · Issue #2685 - I was wondering if there is metaplan to formalize bundling of OAS definitions as well. Ben Hutton and Mike Ralphson did a great job of formalizing JSON Schema 2020-12 in their article and set guidelines how to bundle JSON Schemas when present in OAS definitions. That's a great start, but we have other specification objects that can be bundled within OAS spec.
  • Specify what happens when relative json pointer is `0` · Issue #1121 - Unless I'm missing something, we don't actualy specify what happens when a Relative JSON Pointer is 0 in the Relative JSON Pointer specification.

Interesting Discussions

Interesting Releases

Interesting Blog Posts

Interesting News

Interesting Tweets

Interesting Videos

Interesting People

Conclusion

If there is anything missing from my summary of what is going on in the world of API specifications, please let me know! As part of this process I am working to get folks behind the meetings, discussions, and other goings on to be more public about what they are doing so I have a URL to share. I am also working on updating the home page of the API Specification Toolbox to showcase how you can learn, implement, and contribute to each of the specifications—-once I have up, I will link to more from this regularly summary. My goal is to provide a single place everyone can go to get involved within the communities for each of the API specifications, but also stay up to speed on what is going on each week.