Skip to content

AsyncAPI Messages — Complete Guide

DodaTech Updated 2026-06-28 4 min read

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

Messages are the fundamental unit of data in AsyncAPI. Each message represents a discrete piece of information exchanged through a channel. Defining messages accurately is critical for contract-first event-driven development.

What You'll Learn

  • Message structure and required fields
  • Headers vs payload
  • Message traits for reuse
  • Correlation IDs and message IDs
  • Protocol-specific message bindings

Why It Matters

Messages define the data contract between producers and consumers. Clear message definitions prevent integration issues and enable automatic validation and Code Generation.

Real-World Use

A payment processor defines AsyncAPI messages for each Transaction event. The PaymentAuthorized message includes headers for idempotency keys, a payload with transaction details, and correlation IDs that link authorization to capture events.

Flow Chart

flowchart LR
    A[Message] --> B[Headers]
    A --> C[Payload]
    A --> D[Correlation ID]
    A --> E[Message ID]
    A --> F[Traits]
    B --> G[Metadata]
    C --> H[Business Data]
    D --> I[Request-Reply Correlation]
    E --> J[Idempotency]

Code Examples

Example 1: Complete Message Definition

components:
  messages:
    OrderCreated:
      name: OrderCreated
      title: Order Created
      summary: Event emitted when order is placed
      description: >
        This event is published after order validation
        and payment authorization. It triggers inventory
        reservation and fulfillment workflows.
      contentType: application/json
      tags:
        - name: order
        - name: event
      externalDocs:
        description: Full event catalog
        url: https://docs.example.com/events/order-created
      correlationId:
        $ref: '#/components/correlationIds/orderCorrelationId'
      headers:
        type: object
        properties:
          applicationId:
            type: string
            description: Source application identifier
          eventVersion:
            type: string
            enum: ['1.0', '2.0']
          timestamp:
            type: string
            format: date-time
      payload:
        $ref: '#/components/schemas/OrderCreatedPayload'

Expected output: A fully documented message with headers, payload, correlation ID, and metadata.

Example 2: Message Traits for Reuse

components:
  messageTraits:
    commonHeaders:
      headers:
        type: object
        properties:
          correlationId:
            type: string
          timestamp:
            type: string
            format: date-time
          source:
            type: string
    idempotent:
      headers:
        type: object
        properties:
          idempotencyKey:
            type: string
            description: Key for idempotent processing

  messages:
    OrderCreated:
      traits:
        - $ref: '#/components/messageTraits/commonHeaders'
        - $ref: '#/components/messageTraits/idempotent'
      payload:
        type: object
        properties:
          orderId:
            type: string
    PaymentReceived:
      traits:
        - $ref: '#/components/messageTraits/commonHeaders'
      payload:
        type: object
        properties:
          transactionId:
            type: string

Expected output: Reusable message traits that apply common header patterns across multiple message types.

Example 3: Messages with Protocol Bindings

components:
  messages:
    OrderEvent:
      name: OrderEvent
      bindings:
        kafka:
          key:
            type: string
            description: Order ID used as Kafka message key
          schemaIdLocation: header
          schemaIdPayloadEncoding: confluent
        amqp:
          contentEncoding: gzip
          messageType: order.event
          bindingVersion: '0.2.0'
        mqtt:
          payloadFormatIndicator: 1
          correlationData:
            type: string
          responseTopic: order/events/response
      payload:
        type: object
        properties:
          eventType:
            type: string
          orderId:
            type: string

Expected output: Messages with protocol-specific bindings for Kafka (message key), AMQP (encoding), and MQTT (response topic).

Common Mistakes

Mistake Explanation
Confusing headers with payload Headers are metadata; payload is business data. Put runtime routing info in headers, business data in payload
Missing correlation IDs Without correlation IDs, consumers cannot link related events across different channels
Overusing traits Too many traits make message definitions hard to follow; group related header fields logically
Not specifying content type Always set contentType so consumers know how to deserialize the payload
Ignoring message examples Examples help consumers understand the actual data structure beyond the schema

Practice Questions

  1. What is the difference between name, title, and summary in a message?
  2. How do you correlate related messages across different channels?
  3. When would you use message traits instead of a shared component schema?
  4. How do you define a message with an Avro schema?
  5. What is the purpose of the correlationId field?

Challenge

Define messages for an e-commerce order lifecycle: OrderPlaced, PaymentProcessed, InventoryReserved, OrderShipped, OrderDelivered. Include appropriate headers, correlation IDs, and traits for common metadata.

FAQ

Can a message have both JSON and Avro schemas?

A message has one payload and one schemaFormat. For multi-format support, define separate messages or use a schema registry.

How do I make some header fields required?

Use JSON Schema required array on the headers object: headers: { required: [correlationId], properties: ... }.

What is the difference between message traits and schema components?

Message traits apply to message-level metadata (headers, correlation IDs). Schema components define reusable payload structures.

Can I reference an external schema file?

Yes, use payload: { $ref: './schemas/order.json' } to reference external schema files or schemaFormat for non-JSON schemas.

How do I version messages?

Include a version field in headers or use the message name field with version suffix like OrderCreatedV2.

What is the maximum message size?

Message size limits depend on the broker and protocol, not AsyncAPI. Document any limits in the message description.

Mini Project

Design message definitions for a financial transaction system. Include messages for TransactionInitiated, TransactionAuthorized, TransactionSettled, and TransactionFailed. Use traits for Compliance headers (audit ID, regulatory tags) and protocol bindings for Kafka and AMQP.

What's Next

Learn about message payload design in AsyncAPI

← Previous AsyncAPI Channels — Complete Guide Next → AsyncAPI Message Payloads — Complete Guide

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro

Home Browse Asyncapi