Channels

Message Formats

Define message schemas, content types, and structure for event-driven communication

Messages in AsyncAPI are defined in the components.messages section and referenced from channels and operations. They define the structure and format of data exchanged through your event-driven API.

asyncapi.yml
1components:
2  messages:
3    UserEvent:
4      name: UserEvent
5      title: User Event Message
6      summary: Event triggered by user actions
7      contentType: application/json
8      payload:
9        $ref: '#/components/schemas/UserEventPayload'
10      headers:
11        $ref: '#/components/schemas/MessageHeaders'

Message payload

The payload defines the structure of the message data:

asyncapi.yml
1components:
2  messages:
3    OrderCreated:
4      contentType: application/json
5      payload:
6        $ref: '#/components/schemas/Order'
7  schemas:
8    Order:
9      type: object
10      properties:
11        id:
12          type: string
13          format: uuid
14          description: Unique order identifier
15        customerId:
16          type: string
17          description: Customer who placed the order
18        items:
19          type: array
20          items:
21            $ref: '#/components/schemas/OrderItem'
22        total:
23          type: number
24          format: decimal
25          description: Total order amount
26        createdAt:
27          type: string
28          format: date-time
29          description: When the order was created
30      required:
31        - id
32        - customerId
33        - items
34        - total

Message headers

You can define headers that are sent with your messages:

asyncapi.yml
1components:
2  messages:
3    NotificationEvent:
4      contentType: application/json
5      payload:
6        $ref: '#/components/schemas/Notification'
7      headers:
8        $ref: '#/components/schemas/NotificationHeaders'
9  schemas:
10    NotificationHeaders:
11      type: object
12      properties:
13        messageId:
14          type: string
15          description: Unique message identifier
16        timestamp:
17          type: string
18          format: date-time
19          description: Message timestamp
20        source:
21          type: string
22          description: Source service that generated the message
23        priority:
24          type: string
25          enum: [low, medium, high, urgent]
26          description: Message priority level

Content types

AsyncAPI supports various content types for messages:

asyncapi.yml
1components:
2  messages:
3    JsonMessage:
4      contentType: application/json
5      payload:
6        $ref: '#/components/schemas/JsonPayload'
7    
8    BinaryMessage:
9      contentType: application/octet-stream
10      payload:
11        type: string
12        format: binary
13    
14    TextMessage:
15      contentType: text/plain
16      payload:
17        type: string

Message examples

Provide concrete examples to help developers understand your message format:

asyncapi.yml
1components:
2  messages:
3    UserSignup:
4      name: UserSignup
5      title: User Signup Event
6      contentType: application/json
7      payload:
8        $ref: '#/components/schemas/User'
9      examples:
10        - name: StandardSignup
11          summary: Regular user signup
12          payload:
13            id: "123e4567-e89b-12d3-a456-426614174000"
14            email: "john@example.com"
15            name: "John Doe"
16            signupSource: "web"
17            createdAt: "2024-01-15T10:30:00Z"

Message traits

Use traits to share common message properties across multiple messages:

asyncapi.yml
1components:
2  messageTraits:
3    commonHeaders:
4      headers:
5        type: object
6        properties:
7          messageId:
8            type: string
9          timestamp:
10            type: string
11            format: date-time
12  
13  messages:
14    UserEvent:
15      traits:
16        - $ref: '#/components/messageTraits/commonHeaders'
17      contentType: application/json
18      payload:
19        $ref: '#/components/schemas/UserEventPayload'

This approach helps maintain consistency across your message definitions while reducing duplication.