Skip to main content
AsyncAPI Logo
On this page

AsyncAPI Spec 2.3.0 Release Notes

Dale Lane

·3 min read

The new version of the AsyncAPI specification - 2.3.0 - is now available.

This is a minor release, and it doesn't bring any breaking changes. You can switch to it by modifying the following value in your AsyncAPI file asyncapi: '2.2.0' into asyncapi: '2.3.0'

Servers and channels can now be defined as reusable components

To allow for more flexibility in how AsyncAPI documents are structured and enable content to be reused, servers and channels can now be defined as reusable components.

For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
asyncapi: 2.3.0
servers:
  production:
    $ref: '#/components/servers/myserver'
channels:
  some/events:
    $ref: '#/components/channels/myChannel'
components:
  servers:
    myserver:
      url: "http://localhost:5000/ws"
      protocol: ws
  channels:
    myChannel:
      description: "mychannel"

These are added to the many other aspects of the AsyncAPI specification which can be declared as reusable components. You can see the full list in the Components Object section of the AsyncAPI specification.

This new feature was contributed by Sergio Moya. For more detail, see this pull request and the GitHub issue where this change was discussed.

New protocol bindings

The specification is now extended to support another custom protocol through the bindings feature:

Solace, thanks to Michael Davis. For more details, check out this pull request and binding definition.

Other enhancements

Regular expressions are now Unicode-compliant. This enhancement to the specification from Sergio Moya means that regular expressions (found in pattern and patternProperties fields) are now Unicode-compliant (according to ECMA-262).

This improves compatibility with some JSON Schema parsers. For more details, check out the pull request.

Deprecations

The $ref field in Channel Item Object is now deprecated from AsyncAPI 2.3.0.

The current plan is that the $ref field will be removed from Channel Item Object in AsyncAPI 3.0, and replaced with Reference Object.

For more detail, you can see the discussion about this issue in GitHub.

Tooling support

The following official AsyncAPI tools are already updated to support 2.3.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.13.0, and it contains the 2.3.0 JSON Schema.
  • JavaScript Parser uses latest @asyncapi/specs package and can be used to parse and validate 2.3.0 documents. Upgrade to 1.14.0 version.
  • HTML template uses the latest @asyncapi/react-component package. Upgrade to 0.24.7 version.
  • JavaScript Converter enables conversion from any AsyncAPI version into the 2.3.0 version of the spec. Upgrade to 0.7.0 version.
  • Modelina now also accepts AsyncAPI documents valid against the 2.3.0 version of the spec. Upgrade to 1.46.0 version.
  • Generator uses the latest @asyncapi/parser package, so while generating output, it can validate 2.1.0 documents. Upgrade to 1.9.0 version. Last but not least is the AsyncAPI Studio. Check new studio with this example.

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

Look ahead

We aim to have a regular cadence of releases of the AsyncAPI specification, four times a year. For more information about when to expect future releases, you can see our release process document.

We're also working on the next major release of the AsyncAPI specification: 3.0.0. If you'd like to contribute, or just follow the discussions, you can see the milestone on GitHub.

Photo by Andrew Ridley on Unsplash