asyncapi/spec: the document that defines an event-driven API

One markdown file is the normative document

The repository README states the design decision plainly: the human-readable markdown file is the source of truth for the specification. That sentence settles an argument that comes up repeatedly in specification projects, namely whether the JSON Schema or the prose is authoritative. Here the answer is the prose, and everything else in the ecosystem is derived from it.

The current draft lives at `spec/asyncapi.md` on the master branch and tracks the latest commit. Tagged versions are separate files, so 3.1.0, 3.0.0, 2.6.0, 2.5.0, 2.4.0, 2.3.0, 2.2.0 and 2.1.0 are each a frozen copy. The README marks versions 1.0.0 through 1.2.0 as deprecated, and the 1.x documents are even stored as `README.md` rather than as specification files, which tells you how much the document structure changed.

If you want JSON Schema files rather than prose, the README sends you to a separate repository, `asyncapi/spec-json-schemas`. That split is worth knowing before you start, because it means the schema-driven tooling and the specification text are versioned in two places and can disagree for a short window after a release.

The repository layout tells you what the project actually contains

This is a documentation repository, not a code repository. The language GitHub reports is JavaScript because of the `scripts/` directory, not because there is a published library. The specification itself is one file, and the files around it are the machinery for cutting a release:

spec/asyncapi.md
RELEASE_PROCESS.md
CODEOWNERS

`RELEASE_PROCESS.md` and `.releaserc` are the two files that tell you how a version actually gets cut. A semantic-release configuration sitting next to a written release process is the sign of a project that cares about the mechanics of versioning, which matters for anyone whose CI pins a spec version.

`CODEOWNERS` is present too. For a specification, that is a meaningful signal about how binding a change request is: a document with named owners is a document where a pull request has to go through a review process rather than landing on a whim.

The examples directory is the fastest way to read the document

Twenty example files and a subdirectory, covering more ground than a tutorial would. There are Kafka examples such as `streetlights-kafka-asyncapi.yml` and a Kafka request-reply pair for Adeo. There are MQTT examples, including `streetlights-mqtt-asyncapi.yml` and a version that layers operation security on top. WebSocket coverage is substantial: `slack-rtm-asyncapi.yml`, `websocket-gemini-asyncapi.yml`, `mercure-asyncapi.yml`, and four Kraken examples covering request-reply, message filters in replies and multiple channels.

What makes this directory interesting as documentation is the range of schema shapes it demonstrates. `anyof-asyncapi.yml` and `oneof-asyncapi.yml` exist precisely to show the two composition keywords, and there is a file literally named `not-asyncapi.yml`. `correlation-id-asyncapi.yml` and `application-headers-asyncapi.yml` deal with the plumbing of tracing and headers, and `rpc-client-asyncapi.yml` and `rpc-server-asyncapi.yml` show the same document written from each end of a request-reply interaction.

`examples/README.md` indexes them. Read that file before the specification if your goal is to write a document quickly, then use the spec text to settle the question the example leaves open.

Version 3.0.0 was a breaking change and 3.1.0 added ROS 2

The release history is short and tells you a clear story. Version 2.6.0 is the last of the 2.x line. Version 3.0.0 followed on 2023-12-05 and is labelled a breaking change, with a migration guide on asyncapi.com under docs/migration/migrating-to-v3. Version 3.0.1 came eight days later and is titled INVALID, with a note explaining that no specification changes were made and the release happened only to pick up a library update used for conversion between spec versions.

That v3.0.1 note is a useful detail for tooling authors. It confirms that version conversion is treated as a first-class concern with a maintained library behind it, which means a document written against 2.x has a documented path forward rather than a hand-written rewrite.

Version 3.1.0 is the current release, published on 2026-01-31, and its feature list has exactly one entry: ROS 2 bindings added to the official specification. A specification release that adds a protocol binding and changes nothing else is a good sign about how carefully the maintainers treat the core document. The repository is not archived and the last push was on 2026-09-13, so the draft on master is moving ahead of the 3.1.0 tag.

AsyncAPI and OpenAPI answer different questions

The most common confusion is between AsyncAPI and OpenAPI, and the difference is not about quality, it is about direction. OpenAPI describes an HTTP interface: a set of paths, methods, parameters and request and response bodies. AsyncAPI describes an interface where one party publishes to a channel and other parties subscribe, with the protocol on the wire being Kafka, MQTT, AMQP, STOMP, WebSockets or something else. The repository topics list exactly those protocols alongside specification, reactive and asyncapi.

Because of that split, an AsyncAPI document has a different shape. Servers are named, channels are named, operations bind a channel to a publish or subscribe action, and messages carry payload schemas. `examples/streetlights-kafka-asyncapi.yml` and `examples/streetlights-mqtt-asyncapi.yml` being separate files for the same domain is the clearest illustration of why: the same application concept produces two different documents when the transport differs.

Version 3 widened the scope further by adding ROS 2 bindings, which is a robotics middleware rather than a broker. The direction of travel is toward more transports rather than a narrower HTTP-shaped world.

What this repository does not give you

There is no validator, no editor and no renderer in this repository. The README points elsewhere for each of those: AsyncAPI Studio and AsyncAPI Viewer are separate tools, the JSON Schema files live in `spec-json-schemas`, the examples live in the `asyncapi/asyncapi` repository rather than here, and the case studies are on the AsyncAPI website.

That is not a criticism so much as a warning about where to spend time. If your goal is to author a document in a browser with completion and preview, this repository is the wrong place. If your goal is to understand what a field means and whether the maintainers will accept a change to it, this is the only place, because the spec text and the pull requests that amend it are both here.

Licensing is straightforward: Apache-2.0, with a `NOTICE` file in the tree. For a specification, that licence choice removes the question of whether you can build commercial tooling on top of the document, which is not something every specification can say.

Editorial conclusion

This repository is worth reading closely if you publish events, because every tool in the AsyncAPI ecosystem is built against this text and the version numbers in it. It is not worth reading if you only consume events: there is no runtime here, no broker client, and no code to run. The decision that matters for an adopter is which version to pin. Version 3.1.0 is the current release, published on 2026-01-31, and 2.6.0 is the last of the 2.x line, so a 2.x document is not automatically convertible without a migration guide. Start by opening spec/asyncapi.md on the v3.1.0 tag and reading the fixed fields before the servers block, because that ordering is what every tooling decision downstream assumes.

Frequently asked questions

Official sources

1. asyncapi/spec on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases