Skip to main content
AsyncAPI Logo
On this page

AsyncAPI Spec 2.5.0 Release Notes

Vladimír Gorej

·5 min read

The new version of the AsyncAPI specification - 2.5.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.4.0' into asyncapi: '2.5.0'

Server Variables can be now referenced from inside the Server Object

Previous AsyncAPI 2.4.0 release came with the support of defining Server Variable Objects as reusable components. Unfortunately, AsyncAPI 2.4.0 doesn't allow referencing reusable server variable objects from within the Server Object. So we ended up in a situation where reusable server variable objects can be defined but cannot be reused. AsyncAPI 2.5.0 remedies this deficiency by allowing the use of Reference Objects whenever Server Variable Objects can be used inside the Server.variables field.

The following example is now fully compliant with the updated specification:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
asyncapi: 2.5.0
servers:
  development:
    $ref: '#/components/servers/myserver'
  production:
    $ref: '#/components/servers/myserver'
components:
  servers:
    myserver:
      url: "{stage}.my-server.com:{port}"
      protocol: ws
      variables:
        stage:
          $ref: "#/components/serverVariables/stage"
        port:
          $ref: "#/components/serverVariables/port"
  serverVariables:
    stage:
      default: dev
    port:
      enum: [5000, 6000]
      default: 5000

This new feature was contributed by Vladimír Gorej. For more detail, see Vladimír's /spec #776 pull request and the GitHub issue where Vladimír's change to serverVariables was discussed.

Decorating Server Object with tags

Tags categorize or group resources. 2.5.0 introduces support for defining tags at the Server level, which can be used for many use cases such as grouping servers by their features: environment name, cluster name, visibility, owner, etc.

For example:

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
30
31
32
asyncapi: '2.5.0'
info:
  title: Streetlights Kafka API
  version: '1.0.0'
servers:
  scram-connections:
    url: test.mykafkacluster.org:18092
    protocol: kafka-secure
    description: Test broker secured with scramSha256
    security:
      - saslScram: []
    tags:
      - name: "env:test-scram"
        description: "This environment is for running internal tests through scramSha256"
      - name: "kind:remote"
        description: "This server is a remote server. Not exposed by the application"
      - name: "visibility:private"
        description: "This resource is private and only available to certain users"  
  mtls-connections:
    url: test.mykafkacluster.org:28092
    protocol: kafka-secure
    description: Test broker secured with X509
    security:
      - certs: []
    tags:
      - name: "env:test-mtls"
        description: "This environment is for running internal tests through mTLS"
      - name: "kind:remote"
        description: "This server is a remote server. Not exposed by the application"
      - name: "visibility:private"
        description: "This resource is private and only available to certain users"
channels: {}

This new feature was contributed by Sergio Moya. For more detail, see Sergio's /spec #809 pull request and the GitHub issue where Sergio's change was discussed.

Added missing IBM MQ Operation Binding

We noticed that we overlooked and did not define the Operation Bindings Object in the case of IBM MQ. In AsyncAPI 2.5.0, the definition is empty, but its name is reserved for future use to be consistent with the rest of the bindings.

This change was contributed by Maciej Urbańczyk. For more detail, see Maciej's /spec #840 pull request.

Added new Google Cloud Pub/Sub Bindings

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

Google Cloud Pub/Sub, thanks to Jeremy Whitlock. For more details, check out this pull request and the binding definition.

Clarifications

Here are notable clarifications that got into the AsyncAPI 2.5.0 release. Here is the list of notable clarifications that may have an impact on the tooling authors:

ChannelItem.$ref resolution rules

All references of MUST be in the format of a URL sentence have been substituted with This MUST be in the form of an absolute URL. The meaning of absolute URL is now defined by RFC3986, section 4.3.

Clarification around URL resolution rules

The resolution rules around ChannelItem.$ref field were not clearly defined. AsyncAPI 2.5.0 comes with explicit clarification that the resolution is done as defined by the JSON Reference.

Tooling support

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

  • JSON Schema that supports validation of AsyncAPI documents is updated in our specification JSON schema repository. We updated the @asyncapi/specs package on NPM to version 3.2, containing the JSON Schema document for AsyncAPI Spec 2.5.0.
  • JavaScript Parser can be used to parse and validate 2.5.0 documents. Upgraded to the 1.17.0 version.
  • AsyncAPI React Component allows you to render and validate the documentation of your asynchronous API provided in the AsyncAPI specification format. Upgraded to the v1.0.0-next.43 version.
  • HTML template uses the latest @asyncapi/react-component package. Upgraded to the 0.26.0 version.
  • JavaScript Converter enables conversion from any AsyncAPI version into the 2.5.0 version of the spec. Upgraded to the 1.1.0 version.
  • Generator uses the latest @asyncapi/parser package, so while generating output, it can validate 2.5.0 documents. Upgraded to the 1.9.12 version.
  • Modelina can be used to generate typed models. Upgraded to the 1.0.0-next.11 version.
  • Bundler can be used to generate typed models. Upgraded to the 0.2.3 version.
  • Cupid can be used to generate typed models. Upgraded to the 0.6.20 version.
  • Optimizer can be used to generate typed models. Upgraded to the 0.1.11 version.
  • Glee can be used to generate typed models. Upgraded to the 0.10.23 version.
  • Spectral AsyncAPI Ruleset that you can use for lining of AsyncAPI documents will be released soon. The pull request is ready.
  • Last but not least comes AsyncAPI Studio. Check out AsyncAPI Studio with this YAML example.

Look ahead

We aim to have a quarterly cadence of releases of the AsyncAPI specification. 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 work on the 3.0 release issue.

Photo by Jeremy Thomas on Unsplash