AsyncAPI Spec and parsers update (half September + October 2022)

This is another entry on my monthly (yes, monthly now) update about the AsyncAPI Spec and parsers

As a side note, due to a personal situation, I would be stopping reporting this updates for a couple of months. I still need to figure out if someone else could do it during that time :)

Note This is not an official AsyncAPI update but a personal summary I volunteer to do.

What do I mean by AsyncAPI Spec and parsers update?. As most of the work around the AsyncAPI Spec is not only related to https://github.com/asyncapi/spec, each update will include the most significant recent activity from the following repositories:

• spec
• bindings
• extensions-catalog
• spec-json-schemas
• parser-js
• parser-api
• parser-go
• openapi-schema-parser
• raml-dt-schema-parser
• avro-schema-parser
• tck
• converter-js
• converter-go

Feel free to ask me to include any other repository if you consider it makes sense. Also, in case you want to help me with these updates :)

Spec

2.5 got released! 🚀

2.5.0 got released, and Vladimír Gorej was the Release Coordinator 🙌.

The changes introduced are:

Features

• Server Variables can be now referenced from inside the Server Object (#776) by Vladimír Gorej
• Decorating Server Object with tags (#809) by Sergio Moya.
• Added new Google Cloud Pub/Sub Bindings (#836) by Jeremy Whitlock
• Added schema registry infos to Kafka binding (#115) by Laurent Broudoux
• Other enhancements
  • Clarified ChannelItem.$ref resolution rules (#779) by Vladimír Gorej
  • Clarification around URL resolution rules (#782) by Vladimír Gorej
  • Align wording with RFC 2119 (#818) by Vladimír Gorej

Fixes

• Added missing IBM MQ Operation Binding (#840) by Maciej Urbańczyk

Full Changelog: https://github.com/asyncapi/spec/compare/v2.4.0...v2.5.0

3.0 work is moving on! 🧑‍🍳

Work on 3.0 is moving forward! These are some of the issues and PRs with recent activity:

• Issue: Proposal to solve publish/subscribe confusion by Fran Méndez.
  • Topic: This is one of the core issues regarding 3.0.0. Contains lots of discussions. The latest, started by Iván García, is about some uncertainty around Message Objects ownership and how and where are they declared.
  • This led into several new suggestions and approach:
    • add server and channel traits objects
      • This change will allow extending and reusing both server and channel objects by using traits.
    • A new approach suggestion in feat request/response support by Heiko Henning.
• Issue: Should we have messageId and name fields in Message Object? by Maciej Urbańczyk.
  • Topic: Discussion about removing messageId and name fields from the Message Object in favour of just using the key on the channels map (x in channel[x].messages). There are some caveats this could cause.
  • Please join and leave your opinion ✍️
• Issue: Clarify operation object channel reference by Jonas Lagoni.
  • Topic: There is uncertainty about which channels references inside the Operation Object are supposed to point to, or in other words, which ones are allowed to be used. Also this issue suggest a clarification in the root.channels level regarding the nature of it from the point of view of the Application.
  • Please join and leave your opinion ✍️
• Issue: Should description fields be able to be referenced? by Maciej Urbańczyk.
  • Topic: Discussion around description fields supporting reference to external markdown files.
  • Please join and leave your opinion ✍️
• Issue: Required fields in Operation Trait Object by Maciej Urbańczyk.
  • Topic: It seems that channel and action fields in Operation Trait Object doesn’t make sense, and this issue suggests to remove them.
  • Is there something else we are missing? Please join and leave your opinion ✍️
• Issue: Introduce Info Item Object by Maciej Urbańczyk.
• PR: Unify all referencing mechanisms in v3 by Fran Méndez had a great progress.
  • Topic: At this moment, there is some inconsistency when referencing objects. In some places, $ref is required; in others, the value consists of the object’s id (or the key in the map the object is located in). Removing such an inconsistency is the primary goal of this discussion. More conversations have been flowing around.
  • Please join and leave your opinion. There are a couple of important dicussions of your interest ✍️
• PR: docs: clarify the meaning of components by Fran Méndez is now merged into next-major-spec branch! 🎉
  • Topic: It clarifies the meaning of the Components Object and the meaning everything outside of it. Seems like a trivial change but the reality is that it sets the bases for reusability and what an Application is responsible for.
• PR: Move operations to its own root object by Fran Méndez is now merged into next-major-spec branch! 🎉
  • Topic: As the title says, Operations will not be directly linked inside the channel but in the root document itself. This helps with decoupling and reusing Operations.
• PR: Add new channels object by Fran Méndez is now merged into next-major-spec branch! 🎉
  • Topic: Channel object gets revamped.
    • Name is no longer an address; instead, a new field address holds that information.
    • It is not tied directly to an operation.
    • Messages are still part of the channel but not anymore to the operation.
• PR: Add more reusable objects to the components object by Maciej Urbańczyk is now merged into next-major-spec branch! 🎉
  • Topic: adds External Documentation Object and Tag Object to become reusable objects by allowing them to be declared inside components.
• PR: Move root tags and externalDocs to the info object by Maciej Urbańczyk is now merged into next-major-spec branch! 🎉
  • Topic: move both tags and externalDocs fields from the root of the AsyncAPI document to the Info Object.

As a side note, more Spec 3.0 live meetings have been held 📹. See the list of issues with links to video recordings here.

New Reference(s) tooling is under discussion 🗣️

The main purpose behind this is to support referencing other schemas rather than JSON or convertible to JSON.

Few months ago, Jonas Lagoni opened this draft PR with the very first concepts on how this new referencing standard could work. Now, there is this well-formed GitHub discussion that includes all features and behaviours this new tooling might need to support as well as real-world use cases. Henry Andrews (JSON Schema Co-Author) among other folks joined the discussion by sharing their vast experience in this matter.

If you want to be part of this journey, do not hesitate to join!

spec-json-schemas

v4.0.0 got released! 🎉

Brought by Maciej Urbańczyk, this new version remove unsupported specs from NodeJS export, meaning no more support for versions lower than 2.0.0.

Validation for extensions (from extension-catalog) will be a thing! ⚙️

In the same way there are schemas for bindings, TAHI Siham wants to add those for extensions from the Extensions Catalog. This will become a really powerful addition! 💪

Parameters object now have the proper schema for the reference property 🔧

mastdev fixed the schema for the $ref property in the Parameters Object schema, so now is using a oneOf to allow both references or Parameters object as additionalProperties. This is not a breaking change, because the behavior is not modified, but ensures consistency across all schemas.

See the PR in update schema to resolve reference property issue.

Bug allows to define Operation Traits with a double array 🐛

Jonas Lagoni reported Traits can be defined as double arrays. Some code owners are confirming this is a bug.

parser-js

v2.0.0 beta is out! 🍇

v2.0.0-next-major.8 is the latest beta released, as per today. I encourage you to grab it and test it in your projecs!

At a glance, it has an improved API, it uses Spectral for validating AsyncAPI documents and it has been rewritten to TypeScript improving the developer experience by a lot.

You can see all the pending work on Road to v2.0.0.

All the changes are being merged into the next-spec-major branch and brought by Maciej Urbańczyk, and Sergio Moya.

bindings

Allow using scalar types for some Kafka bindings values 🥂

Viacheslav Poturaev submitted the PR feat: kafka bindings with support for scalar parameter values where it adds support for not only using Schema type for some of the Kafka bindings values but also directly use a scalar such as a plain string.

The PR is already approved but not merged yet, so you are still able to review! 👀

Adding session expiry interval to MQTT5 bindings ⏱️

Shreyansh Jain wants to add sessionExpiryInterval field to the MQTT5 binding so it can be used both when generating code or for letting the user of the API know the expected session expiry interval.

Please, see the PR and add your thoughts ✍️.

avro-schema-parser

Rewrite to TypeScript + implement the new Parser-JS 2.0 interface 🤝

Implement new Parser-js interface + migrate to TypeScript by Sergio Moya ports this schema parser to TypeScript and implements the new Schema Parser Interface available in the future Parser-JS 2.0.

The PR is still open and waiting for more feedback! 👀

openapi-schema-parser

Rewrite to TypeScript + implement the new Parser-JS 2.0 interface 🤝

Rewrite to TS and adjust to the v2 ParserJS by Maciej Urbańczyk ports this schema parser to TypeScript and implements the new Schema Parser Interface available in the future Parser-JS 2.0.

The PR is still open and waiting for more feedback! 👀

raml-dt-schema-parser

Rewrite to TypeScript + implement the new Parser-JS 2.0 interface 🤝

Rewrite to TS and adjust to the v2 ParserJS by Maciej Urbańczyk ports this schema parser to TypeScript and implements the new Schema Parser Interface available in the future Parser-JS 2.0.

The PR is still open and waiting for more feedback! 👀

extensions-catalog

MVP for making the Extensions Catalog finally useful! 🚀

MVP integration of extensions catalog with AsyncAPI tools to make extension catalog useful is being taken by TAHI Siham. The idea is to simplify the approach decided on the very beginning so it can provide value to the community soonish.

You can take a look to some of the TODOs for making this happen:

• Cleanup/simplify this repo
• Create the JSON Schema files for the extensions (See )