This is a special entry on my bi-weekly update about the AsyncAPI Spec and parsers. During summer, I will be posting updates every one or two months. The reason is that there is less activity in the community during this period due to summer holidays, etc. (including me 😎).
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.4.1 is going to be released soon 🔧
Just a light patch over 2.4.0 but needed to clarify in the spec how reusability of Server Variable Objects work. See fix: allow reusability of Server Variable Objects by Vladimir Gorej.
2.5 work has been started! 🚀
AsyncAPI release cadence mentions that releases will happen on the following months:
- January -> 2.3.0
- April -> 2.4.0
- June -> Nothing!
- September
However, there was nothing to be released by June; therefore, no release happened. This means any proposal for 2.5.0 will potentially be released in September.
At this moment, the RFCs that can potentially target the 2.5.0 version are:
STOMP protocol
At this moment, the bindings for STOMP protocol are not defined, but Crain started an excellent discussion on Proper STOMP Protocol Bindings issue with some proposals on how to start defining this binding.
We are looking for help there, so as always, you are more than welcome to join the discussion 🖐️
Tags for Server Objects
Tags were used on different parts of an AsyncAPI document like Operations. However, adding Tags to Servers were not possible yet. Some use cases motivated this new addition, such as Allowing grouping servers by their environment and other properties.
See feat: add tags field to Server Object by Sergio Moya.
3.0 work is moving on! 🧑🍳
Work on 3.0 is moving forward slowly. These are the issues and PRs with recent activity:
- Creating the AsyncAPI Domain specification by Fran Méndez.
- Topic: This time, Fran introduces a completely new spec for replacing those files people are almost forced to create when defining broker-based architectures, including all shareable objects.
- This one requires the attention from “all of you” since it could become a huge new thing, in terms of concepts, for the AsyncAPI ecosystem. 🆘
- Heiko Henning is now championing Support request/reply pattern 👨🚀🚀
- Topic: Created initially by Adrian Hope-Bailie, this issue attempts to allow defining a request/reply pattern into AsyncAPI spec Channels and Operations.
- Your review and participation in this issue are more than welcome! 🆘
- You can watch several live meetings that have been held regarding this topic:
- Introduce
Info Item Objectby Maciej Urbańczyk.- Topic: Identifying common info fields for all main objects of the spec and creating a common object to be reused.
- There is an ongoing discussion on the PR that you might want to check.
- move root tags and externalDocs to the info object by Maciej Urbańczyk.
- Topic: move both
tagsandexternalDocsfields from the root of the AsyncAPI document to the Info Object.
- Topic: move both
- add more reusable objects to the components object by Maciej Urbańczyk.
- Topic: adds
External Documentation ObjectandTag Objectto become reusable objects by allowing them to be declared insidecomponents.
- Topic: adds
- extend Schema Object to allow defining custom formats by Maciej Urbańczyk.
- Topic: Allow custom formats on Schema Object, and deprecate the
schemaFormatfield in theMessage Object.
- Topic: Allow custom formats on Schema Object, and deprecate the
- add metadata object, server trait and channel trait by Maciej Urbańczyk.
- Topic: The original idea was to define a new
Metadata Objectwith some common fields that other spec objects could reuse. - After a few iterations, the direction it took is that some of those fields would be added to the final objects rather than inherit them from a new object.
- Topic: The original idea was to define a new
- External docs/Contact as collection by Maciej Urbańczyk.
- Topic: allow both
externalDocsandcontactfields to accept a collection of the expected objects instead of just one.
- Topic: allow both
As a side note, more Spec 3.0 live meetings have been held 📹. See the list of issues with links to video recordings here.
Measuring the adoption of AsyncAPI Spec
Time ago, Lukasz Gornicki brought the idea of Measuring AsyncAPI spec adoption. For that, he suggested measuring the amount of AsyncAPI users that work with AsyncAPI documents by:
- Adding AsyncAPI JSON Schema files into JSON Schema Store. You can read more about the reason behind this in Why would I use schema store issue.
- Collecting metrics about downloads of AsyncAPI JSON Schema files.
To achieve that, Sergio Moya ended up with:
- Coding a new Netlify Edge Function that redirects traffic from
asyncapi.com/definitions/<file>.jsonandasyncapi.com/schema-store/<file>.jsonto the raw GitHub URL’s for the definitions and schemas avaialble in https://github.com/asyncapi/spec-json-schemas. - In the same Netlify Edge Function, to send metrics to an AsyncAPI New Relic account. You can see a screenshot of the internal metrics dashboard:
- Updating AsyncAPI entry in JSON Schema Store to serve the JSON Schema files from the new paths on the AsyncAPI website. See feat: update AsyncAPI schema URLs.
- There are more pending fixes (like Schema Store plugins supporting all versions of the spec), but mainly all is working as expected.
spec-json-schemas
v3.0.0 got released! 🎉
Brought by Jonas Lagoni, this new version introduces split definitions and bundling behavior to provide better maintainability of the JSON Schema files.
Bindings JSON Schema files are now in spec-json-schemas repository.
From now on, and thanks to Jonas Lagoni, all AsyncAPI JSON Schema files are together under the same repository, making it easier to find and distribute.
In this other PR, add specific binding schemas, Jonas Lagoni is also splitting bindingsObject into the 4 specific bindings for operation, channel, message, and server.
The next step is to figure out how to version the binding schemas alongside spec schemas.
parser-js
v1.15.1 got released! 🎉
This new release includes a commit that fixes an inconsistent behavior of message/messages/hasMultipleMessages. The PR, brought by Tenischev
The rewrite to Typescript is moving forward.
Migrate project to TypeScript moved forward and now, all the models got ported to Typescript, all of them following the Intent-driven API of Parser-API, which has been also updated in parallel. Big shout-out to Maciej Urbańczyk, who did most of the job during this time! 🥇🥇
You can see all the work on next-spec-major branch.
Improving generated $id for Schemas
Heiko Henning submitted a PR adding new options to generate nice $id. This change will improve UX when generating code or documentation.
The PR is a Work In Progress, so you are encouraged to drop a review! ✍️
parser-api
v1.0.0-alpha.3 is out, now including all changes introduced on latest work on parser-js
Parser-API contains now all changes introduced on latest work on parser-js. See the PR at # docs: update parser-api by magicmatatjahu.
bindings
Adding support for multiple HTTP methods
souvik is [adding support for multiple methods in HTTP bindings] in an OpenAPI fashion. The issue is still waiting to be reviewed after the last changes it introduced, but basically, it attempts to remove one considerable limitation: only one HTTP method is allowed as of today. This requires a few reviews, thinking out of the box, and finding the best way to achieve that, and this is a perfect starting point!
A deeper discussion about this topic is being handled in [FEATURE REQUEST] HTTP with multiple methods as well.
bindings also had some more activity
- fix: move WebSockets binding details to server and remove the method option PR has been reopened.
converter-js
v1.0.0 got released! 🎉
Brought by Maciej Urbańczyk, this release removes CLI from the repo as it is now an independent tool living in https://github.com/asyncapi/cli. It also does some cleanups.