AsyncAPI

The Info Object provides metadata about the API. This is the root-level info field and contains essential identification details.

• title: A human-readable title for the application/API.
• version: The version of the AsyncAPI document (not the API implementation).
• description: A rich text description of the API.
• contact and license: Optional objects for maintainer and usage rights information.

This section is analogous to the info object in an OpenAPI document and is crucial for documentation and tooling.

The Servers Object defines the network locations where the application's channels are hosted. It is a map of server definitions under the servers field.

Each server definition includes:

• url: The network address (e.g., mqtt://broker.example.com:1883, kafka://cluster.prod:9092).
• protocol: The communication protocol (e.g., mqtt, kafka, amqp, ws).
• description: A human-readable explanation.
• variables: For parameterized server URLs.
• security: An array of required security schemes.

Servers provide the runtime connection context for channels.

The Channels Object is the core of the specification, describing the available event pathways. It is a map under the channels field where each key is a channel name, often representing a topic, queue, or event name.

A channel item defines:

• address: A runtime expression for the full channel path (often derived from the key).
• description: Explains the channel's purpose.
• publish and/or subscribe Operation Objects: Describe the messages that can be sent or received on this channel.
• parameters: For channels with variable path segments (e.g., user/{userId}/events).

Channels abstract the specific messaging infrastructure.

An Operations Object defines an action that can be taken on a channel, specified within a channel's publish or subscribe field. It describes the intent and characteristics of message flow.

Key fields include:

• operationId: A unique string used to identify the operation in code generation.
• message: A reference to or definition of the Message Object sent or received.
• summary and description: Human-readable details.
• security: Security requirements specific to this operation.
• traits: For applying reusable operation patterns.

The publish operation sends a message to the channel; subscribe receives from it.

The Messages Object defines the format and semantics of a discrete piece of data communicated via a channel. It can be defined inline within an operation or referenced from the top-level components.messages section.

A message definition includes:

• payload: A JSON Schema object defining the structure of the message body.
• headers: A schema for protocol-specific headers or metadata.
• correlationId: Describes an identifier for tracing message causality.
• contentType: The MIME type of the payload (e.g., application/json, avro/binary).
• name and title: For identification.

Messages ensure producers and consumers agree on data contracts.

The Components Object is a container for reusable schema elements, located at components. It promotes modularity and reduces duplication within the AsyncAPI document.

Common reusable component sections include:

• schemas: Reusable data models defined with JSON Schema.
• messages: Reusable message definitions.
• securitySchemes: Authentication and authorization definitions (e.g., userPassword, X509, httpApiKey).
• parameters: Reusable channel parameters.
• correlationIds: Reusable correlation ID objects.
• operationTraits and messageTraits: Reusable sets of operation or message properties.

Objects within components are referenced using the $ref keyword.

Event-Driven Architecture (EDA) is a software design paradigm where system components communicate by producing and consuming events. AsyncAPI is the specification standard for formally describing the APIs within an EDA.

• Core Principles: Decoupling, asynchronous communication, and reactivity. Components are notified of state changes (events) rather than being called directly.
• AsyncAPI's Role: Provides the contract for the event mesh, detailing the available event channels, message formats, and the protocols used (e.g., Kafka, MQTT, WebSockets).
• AI Agent Role: Agents act as event producers or consumers, using the AsyncAPI document as a map to participate in the EDA.