AsyncAPI Specification Structure — Complete Guide

In this tutorial, you will learn about AsyncAPI Specification Structure. We cover key concepts, practical examples, and best practices to help you master this topic.

The AsyncAPI specification defines a JSON/YAML document structure for describing event-driven APIs. Understanding each section of the document is essential for creating complete and valid specifications.

What You'll Learn

• Top-level fields of an AsyncAPI document
• How to structure info metadata
• Server and channel definitions
• Message and payload schemas
• Components and reusability

Why It Matters

A well-structured AsyncAPI document serves as the single source of truth for your event-driven system. Incorrect structure leads to broken tooling, incomplete documentation, and confusing Code Generation.

Real-World Use

A fintech company maintains AsyncAPI specs for all 15 of its Microservices. Each spec follows the same structure with reusable components, making it easy for new developers to understand event flows and for automated tools to generate monitoring dashboards.

Flow Chart

flowchart TD
    A[AsyncAPI Document] --> B[Info]
    A --> C[Servers]
    A --> D[Channels]
    A --> E[Components]
    B --> F[Title, Version, Description]
    C --> G[URL, Protocol, Security]
    D --> H[Publish/Subscribe]
    D --> I[Message Definitions]
    E --> J[Schemas]
    E --> K[Security Schemes]
    E --> L[Message Traits]

Code Examples

Example 1: Complete AsyncAPI Document Structure

asyncapi: '2.6.0'
id: 'urn:com:example:order-service'
defaultContentType: application/json

info:
  title: Order Service Events
  version: '2.1.0'
  description: Event-driven API for order lifecycle
  contact:
    name: API Team
    email: api@example.com
  license:
    name: Apache 2.0
    url: https://apache.org/licenses/LICENSE-2.0

servers:
  production:
    url: kafka://events.example.com:9092
    protocol: kafka
    description: Production Kafka cluster
    security:
      - saslScram: []

channels:
  order/created:
    description: Triggered when new order is placed
    parameters:
      eventVersion:
        $ref: '#/components/parameters/eventVersion'
    publish:
      operationId: emitOrderCreated
      summary: Emit order created event
      message:
        $ref: '#/components/messages/OrderCreated'
      
  order/fulfilled:
    subscribe:
      operationId: onOrderFulfilled
      summary: Receive order fulfillment events
      message:
        $ref: '#/components/messages/OrderFulfilled'

components:
  messages:
    OrderCreated:
      name: OrderCreated
      title: Order Created Event
      summary: Event emitted when order is placed
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/commonHeaders'
      payload:
        $ref: '#/components/schemas/OrderEvent'

  schemas:
    OrderEvent:
      type: object
      required: [orderId, userId, total]
      properties:
        orderId:
          type: string
        userId:
          type: string
        total:
          type: number

  messageTraits:
    commonHeaders:
      headers:
        type: object
        properties:
          correlationId:
            type: string
          eventTimestamp:
            type: string
            format: date-time

  securitySchemes:
    saslScram:
      type: scramSha256
      description: SASL/SCRAM authentication

  parameters:
    eventVersion:
      description: Event schema version
      schema:
        type: string
        enum: ['v1', 'v2']

Expected output: A complete AsyncAPI document with all major structural sections properly defined.

Example 2: Minimal Valid Document

asyncapi: '2.6.0'
info:
  title: Minimal Service
  version: '1.0.0'
channels:
  events:
    publish:
      message:
        payload:
          type: object
          properties:
            id:
              type: string

Expected output: The minimum viable AsyncAPI document with only required fields: asyncapi version, info, and at least one channel.

Example 3: Multi-File Structure with $ref

# main.yaml
asyncapi: '2.6.0'
info:
  title: Multi-File Service
  version: '1.0.0'
servers:
  $ref: './servers.yaml'
channels:
  $ref: './channels.yaml'
components:
  $ref: './components.yaml'

# servers.yaml
servers:
  production:
    url: mqtt://mqtt.example.com
    protocol: mqtt
    description: MQTT Broker

# channels.yaml
channels:
  sensor/data:
    publish:
      message:
        $ref: './components.yaml#/messages/SensorData'

Expected output: An AsyncAPI document split across multiple files for better maintainability, with $ref references linking them together.

Common Mistakes

Practice Questions

1. What are the required fields in an AsyncAPI document?
2. How do you reference reusable components in AsyncAPI?
3. What is the difference between publish and subscribe in a channel?
4. How do you organize a large AsyncAPI specification across multiple files?
5. What information goes in the info section?

Challenge

Create a multi-file AsyncAPI specification for an IoT system. Include server definitions for MQTT, channels for sensor data and device commands, and reusable message components for temperature, humidity, and pressure readings.

FAQ

Mini Project

Design a complete AsyncAPI specification for a real-time chat application. Include server definitions for Websocket, channels for messages and typing indicators, user presence events, and reusable message components with proper examples.

What's Next

Learn how to define channels in AsyncAPI