Asyncapi

AsyncAPI allows you to describe the surface area of event-driven APIs in a machine-readable way, providing a way of defining the protocol, channels, topics, messages, and the schema that are being published and subscribed to. AsyncAPI is a sister specification to the OpenAPI specification, sharing some common properties, as well as support of JSON Schema, but AsyncAPI provides a wider number of protocols than OpenAPI is designed to cover.

Also known as: AsyncAPI Specification, AAI

Standards

AsyncAPI Initiative (Linux Foundation) AsyncAPI Specification 3.0.0
AsyncAPI Initiative (Linux Foundation) AsyncAPI Specification 2.6.0
AsyncAPI Initiative AsyncAPI Bindings
IETF (JSON Schema WG) JSON Schema Draft 07 (default schema format)
CNCF CloudEvents 1.0.2
OASIS MQTT 5.0
OASIS AMQP 1.0

Media Types

application/vnd.aai.asyncapi — IANA-registered for AsyncAPI in YAML.
application/vnd.aai.asyncapi+json — IANA-registered for AsyncAPI in JSON.
application/cloudevents+json — CloudEvents — Common event envelope referenced from AsyncAPI messages.

OpenAPI Expression

asyncapi (AsyncAPI 3.x) — Version string at the root of every document.
info (AsyncAPI 3.x)
servers (AsyncAPI 3.x) — Broker endpoints and protocol metadata.
channels (AsyncAPI 3.x) — Addressable paths/topics where messages are exchanged.
operations (AsyncAPI 3.x) — Send/receive actions bound to a channel (new shape in 3.0).
components.messages (AsyncAPI 3.x)
components.schemas (AsyncAPI 3.x)
components.messageBindings (AsyncAPI Bindings) — Protocol-specific metadata (Kafka, AMQP, MQTT, WebSocket, etc.).

Governance Rules

asyncapi2-schema (Spectral built-in (asyncapi rulesets)) — Document must validate against the AsyncAPI schema.
asyncapi-operation-operationId (Spectral built-in) — Every operation should have a unique operationId.
asyncapi-message-name (Spectral built-in) — Messages should have a name.
asyncapi-channel-no-trailing-slash (Spectral built-in) — Channel addresses should not end with a trailing slash.

Risk & Compliance

OWASP:

OWASP API Security Top 10: API8:2023 Security Misconfiguration — broker auth, ACLs, and TLS are easy to misconfigure
OWASP API Security Top 10: API9:2023 Improper Inventory Management — undocumented topics become shadow event surface

Compliance:

SOC 2 CC6.1 — logical access to brokers and topics
GDPR — event payloads frequently carry personal data; lineage and retention need to be tracked

Security: Event-driven systems leak through topics, not URLs. Document every published/subscribed topic, schema-validate payloads at the broker boundary, enforce per-topic ACLs, and pin schema versions to avoid poison-message replay.

Tools

AsyncAPI Studio — Editor (Apache-2.0)
AsyncAPI Generator — Codegen / Docs (Apache-2.0)
AsyncAPI CLI — CLI (Apache-2.0)
Microcks — Mock / contract test (Apache-2.0)
Spectral (with asyncapi ruleset) — Linter (Apache-2.0)
Modelina — Schema-to-model codegen (Apache-2.0)

Suggested Metrics

asyncapi_coverage — Share of produced/consumed topics described in an AsyncAPI document.
asyncapi_schema_violations — Count of messages rejected at the broker boundary for schema mismatch.
asyncapi_breaking_changes — Count of breaking changes detected between AsyncAPI versions.
broker_topic_inventory_delta — Difference between topics in the broker and topics described in AsyncAPI.

Example Implementations

Slack — Events API surface lends itself to AsyncAPI modeling for channel/message events.
Salesforce — Platform Events and CDC streams are described with AsyncAPI by some teams.
Adyen — Publishes AsyncAPI for webhook event payloads.

Related Properties

Openapi
Json schema
Webhooks