asyncapi/spec

The AsyncAPI specification allows you to create machine-readable definitions of your asynchronous APIs.

Summary

The asyncapi/spec repository is the source of truth for the AsyncAPI specification, an open standard for describing asynchronous and event-driven APIs in a machine-readable format. The current release is version 3.1.0, and the specification is maintained primarily as a human-readable Markdown document under the Apache-2.0 license. The repository's stated goal is to let teams define their event-driven interfaces the way OpenAPI defines REST endpoints.

What it is useful for

AsyncAPI is useful when a team needs a single, declarative file that describes which channels, topics, and messages a service publishes or consumes, rather than scattered wiki pages or tribal knowledge. The format is protocol-agnostic, and the repository's topics list explicitly covers AMQP, Kafka, MQTT, STOMP, and WebSockets, so the same definition can describe a Kafka topic consumer, an MQTT subscription, or a WebSocket handler without rewriting it per transport. Practical uses include documenting message contracts between teams, generating documentation from a spec file, and giving downstream tooling a stable input to validate or process. The README also notes that JSON Schema files for validation live in a separate repository, asyncapi/spec-json-schemas, which is relevant for anyone wanting machine-checkable conformance.

How engineers can use it

The repository itself is a specification, not a runnable library, so the README does not include installation or build steps; it is meant to be read and referenced. The README states that spec/asyncapi.md tracks the latest commit on master and that the Markdown file is the source of truth. Engineers typically:

1. Read spec/asyncapi.md to learn the structure (info, servers, channels, operations, messages).
2. Pick a target version. The README lists 3.1.0 as the latest, with 3.0.0, 2.6.0, 2.5.0, 2.4.0, 2.3.0, 2.2.0, 2.1.0, 2.0.0, and the 1.x line also linked. The 1.x releases are explicitly marked deprecated.
3. Author an asyncapi.yaml or asyncapi.json document for their system.
4. Validate it against the versioned JSON Schemas in asyncapi/spec-json-schemas.

The README points to the examples directory of the asyncapi/asyncapi repository for sample documents, and the contributor's guide is in CONTRIBUTING.md for anyone proposing changes to the spec itself. Because behaviour and fields differ between the 2.x and 3.x lines, pin a version before integrating the format with parsers or documentation tools.