API Specifications Update for August 25th, 2021

I try to stay up to speed with what is happening across the leading API specifications each week. 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. Providing 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 a snapshot of what I see happening.

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.

Interesting Discussions

Interesting Releases

Interesting Blog Posts

  • JSON Schema bundling finally formalised - OpenAPI Initiative - I’ve been known to say “If you haven’t rewritten your OpenAPI bundling implementation recently, then you don’t support OpenAPI 3.1”. This observation may be true, but perhaps some more detail would be helpful? When implementing support for OAS 3.1 and JSON Schema draft 2020-12 in oas-kit, reading the sections of the JSON Schema spec on bundling compound documents, I still wasn’t totally clear on what was expected of compliant tooling. Thankfully, Ben Hutton is here to set the record straight with a worked example. – Mike Ralphson, OAI TSC
  • The State of API Development and the Upcoming ASC 2021 – A closeup with Mandy Whaley, Azure Dev Tools, Microsoft - OpenAPI Initiative - To find out more about ASC 2021, we talked with Mandy Whaley, Partner Director of Product, Azure Developer Tools at Microsoft. Whaley is a life-long software developer who has worked in development teams of all sizes and types.

Interesting News

Interesting Tweets

Interesting Videos

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.