Skip to main content
AsyncAPI Logo
On this page

AsyncAPI Spec 2.1.0 Release Notes

Lukasz Gornicki

·4 min read

The last AsyncAPI release (2.0.0) took place on the 11th of September, 2019. In 2020 the focus went into growing community and adoption and stabilization of basic tooling for specification. This year was a year of "formalizm" 😃 aka getting into the foundation, setting up governance model and contribution guide to enable work on next spec release. We are good to go forward. The 2.1.0 release is out in the wild 🎉

Message examples object extended with additional fields

Thanks to work done by Laurent Broudoux, you can now clearly describe message examples. New properties name and summary are optional. These properties help not only to properly describe the example in documentation but make it easier to work with mocking and testing tools (like microcks), so you can better identify what example to use for mocking and what it does.

Example of new properties added to existing WebSocket example for Gemini API:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
components:
  messages:
    marketData:
      summary: Message with marked data information.
      description: |
        The initial response message will show the existing state of the order book. Subsequent messages will show all executed trades, as well as all other changes to the order book from orders placed or canceled.
      payload:
        $ref: '#/components/schemas/market'
      examples:
        - name: updateMessage
          summary: Example of an update message that contains a change in price information.
          payload:
            type: update
            eventId: 36902233362
            timestamp: 1619769673
            timestampms: 1619769673527
            socket_sequence: 661
            events:
              - type: change
                side: bid
                price: '54350.40'
                remaining: '0.002'
                delta: '0.002'
                reason: place
        - name: heartbeatMessage
          summary: Example of additional heartbeat message when you enable them. 
          payload:
            type: heartbeat
            socket_sequence: 1656

Rendering of new example properties in React component and HTML template:

For more details, check out this pull request.

New protocol bindings

The specification is now extended to support the following custom protocols through the bindings feature:

Custom schema formats mandatory vs recommended

Support for Avro and OpenAPI schemas changed from mandatory to recommended through contribution from Fran Mendez. For more details, check out this pull request

New security schemes

Thanks to Dale Lane, you can now describe secured Kafka clusters with SASL security schemes (scramSha256, scramSha512, gssapi). For more details, check out this pull request.

Old new defaultContentType property in root object

We used and supported defaultContentType property to specify the default content type when encoding/decoding a message's payload. Lucas Block spotted that we do not have it defined in the specification. For more details, check out this pull request.

Tooling support

The following official AsyncAPI tools are already updated to support 2.1.0 version of the specification:

  • JSON Schema that supports validation of AsyncAPI documents is updated in this repository. Also @asyncapi/specs package has been updated on NPM to version 2.8.0, and it contains the 2.1.0 JSON Schema.
  • JavaScript Parser uses latest @asyncapi/specs package and can be used to parse and validate 2.1.0 documents. Upgrade to 1.7.0 version.
  • AsyncAPI Generator uses the latest @asyncapi/parser package, so while generating output, it can validate 2.1.0 documents. Upgrade to 1.8.0 version
  • Generator filters functions getPayloadExamples and getHeadersExamples support new message example properties. Upgrade to 2.0.0 version.
  • React component supports rendering of new message example properties. Upgrade to v1.0.0-next.10 version.
  • Markdown template supports rendering of new message example properties. Upgrade to 0.14.0 version.
  • HTML template uses the latest @asyncapi/react-component package. Upgrade to 0.23.0 version.
  • JavaScript Converter enables conversion from any AsyncAPI version into the 2.1.0 version of the spec. Upgrade to 0.5.0 version.
  • Modelina now also accepts AsyncAPI documents valid against the 2.1.0 version of the spec. Upgrade to 0.16.0 version.

Last but not least is the AsyncAPI Playground. Check new playground that uses latest HTML template and Markdown template with this example.

Big thanks to Maciej Urbanczyk and Jonas Lagoni for updating most relevant tooling.

This is not all! Not only official AsyncAPI tools are updated. Thanks to Laurent Broudoux also Microcks now supports version 2.1.0 and its new example's properties. Upgrade to 1.3.0 version.

Thank you

I want to send a special thank you to Aayush Kumar Sahu, who helped us to automate the part of the release responsible for updating the specification Markdown document on the AsyncAPI website, right after triggering the release, even the release candidate. Thank you 🙇.

Photo by Doug Swinson on Unsplash