--- published: true layout: post title: 'API Specifications Update for September 1st, 2021' image: https://kinlane-productions2.s3.amazonaws.com/algorotoscope-master/citizenship-shipping-docs-cranes.jpg tags: - API Specification Update ---

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

Open Community (TDC) Meeting, Thursday 26 August 2021 · Issue #2680 - The weekly OAI TDC meeting to move forward the spec.
JSON Schema Office Hours · Discussion #34 - The weekly office hours for the JSON Schema specification.
API Specification Office Hours · Issue #138 - The weekly office hours across all of the API specifications.
AsyncAPI SIG Meeting for August 31, 2021 - The regular AsyncAPI SIG meeting to move forward the specification.

Upcoming Meetings

Open Community (TDC) Meeting, Thursday 26 August 2021 - The upcoming weekly TDC meeting.
JSON Schema Public Office Hours - The weekly public office hours for JSON Schema.
AsyncAPI SIG Meeting - The regular occurring AsyncAPI SIG meeting.
API Specification Office Hours · Issue #138 - The weekly office hours across all of the API specifications.
Open Community (TDC) Meeting, Thursday 02 September 2021 - The weekly OAI TDC meeting to move forward the spec.

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

Why OpenAPI 3.1.0 does not allow schema references in Parameter & Media Type objects? · Discussion #2676 · OAI/OpenAPI-Specification - It feels very strange for me that Parameter Object (schema field) and Media Type Object (schema field) do not allow Reference Object to be passed.
The website should redirect to HTTPS · Discussion #39 · json-schema-org/community - Not sure if this is intentional behavior (for backwards-compatibility purposes perhaps?), but every page of the json-schema.org website can be accessed over plain HTTP. The website doesn't transfer sensitive information, but it is a considered a good practice to redirect HTTP to HTTPS given that HTTPS is already supported.
AsyncAPI Hack & Conf 2021 - Sponsor Tiers · Discussion #58 - Discussion around the sponsorship for AsyncAPI Hack and Conference.
AsyncAPI specification structure visualizer · Discussion #55 - A conversation around a visualizer for AsyncAPI.
AsyncAPI Hack & Conf 2021 - Budget · Discussion #56 - Discussions about the budget for ASyncAPI Hack & Conference.

Interesting Releases

Release v1.0.0-next.18 · asyncapi/asyncapi-react - render binding in capsule instead of drop down
Release v0.2.0 · asyncapi/dotnet-nats-template - client and channel generation
Release v0.26.0 · asyncapi/modelina - example function for TS class renderer
Release v0.27.0 · asyncapi/modelina - pass options to processors.
Release v0.5.0 · asyncapi/cli - add support for version -v alias.
Release v0.6.0 · asyncapi/cupid - change package name and update readme.

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.
AsyncAPI Hackathon and Conference - Get Yourself Ready | AsyncAPI Initiative for event-driven APIs - AsyncAPI Community organizes two important events in the second half of 2021: Hackathon in October Online conference on November 16-1*. We do not have the website ready yet. We do not have the call for proposals opened yet. Don't worry though, all logistics are in progress.

Interesting News

Get started with FastAPI | InfoWorld - Take advantage of the FastAPI web framework and Python to quickly create snappy, OpenAPI-compliant web APIs — and full websites, too.
API Specifications Calm Chaos of Digital Transformation (Part 1) -
Redocly August 2021 Updates - VSCode
try { work(); } finally { code(); } -

Interesting Tweets

kubeshop/kusk (0.1.1): Kusk makes your OpenAPI definition the source of truth for API resources in your cluster https://t.co/iOppuZ0ayg
— Built with Go (@RealGophersShip) September 1, 2021

Loved participating on this panel. #OpenAPI is the future of #restauranttechnology #restaurants #restaurantindustry. Thank you so much to @michaelwolf and @TheSpoonTech for having us! https://t.co/FhKEXFBbJx
— Restaurant Technology Network (@RestTechNet) August 31, 2021

In August, we received $2,255 from 8 backers and we spent $2,496. Our current balance is $21,521.

Thank you! 🙏https://t.co/msi6LURKcP
— AsyncAPI Initiative (@AsyncAPISpec) September 1, 2021

Learn about the process of sending Json schema formatted topics from an HDInsight managed Kafka standalone server to a MySQL DB! #Azure https://t.co/CUZOkorFTd pic.twitter.com/cn6sDcfVqO
— Tech Community (@MSTCommunity) September 1, 2021

New month, new @OpenPolicyAgent release! v0.32.0 features (experimental) disk-based storage, new trigger system for plugins, improved JSON schema support, http.send for UNIX domain sockets, plus many improvements to docs, performance, and much more! https://t.co/RKsgC2dZtg
— Anders Eknert (@anderseknert) September 1, 2021

📦 node-red-contrib-json-multi-schema (1.3.1)

Generic JSON data pipeline tools, with dynamic transformation (using JSONata rules), resolving JSON Schema (using JSONata rules), and then validation (using JSON Schema). For Node-RED and for command-li…https://t.co/8SRiUxBjsN
— Node-RED Nodes (@red_nodes) August 31, 2021

quicktype: Generate types and converters from JSON, Schema, and GraphQL
⭐️ 6919#rustlang https://t.co/385i6XLNfW
— Awesome Rust Repositories (@RustRepos) August 26, 2021

Interesting Videos

Interesting People

Documenting the REST endpoints is important and, as a developer, you have to do it!
How can we document our REST endpoints without spending so much time?
We can use @MicroProfileIO OpenAPI.
🧵Thread
— Giuseppe Scaramuzzino (@GiuseScara) August 27, 2021

✨I've joined @getpostman to focus on the #OpenSource (OSS) side of the Postman spaceship.✨

I was hired directly by the partner OSS maintainer team that owns the @AsyncAPISpec initiative, which moved under the @LinuxFoundation. pic.twitter.com/Uv3OvmJxKr
— Alejandra🍒🍓🍎 y Canela🐕‍🦺 (@QuetzalliAle) August 30, 2021

I’m very grateful to the JSON schema generator at https://t.co/890FE70FVi for easing my way into defining our own schema. pic.twitter.com/1IpEWxXJZi
— Jan-Piet Mens (@jpmens) August 29, 2021

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.