Message Formats

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

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

1 components:
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

1 components:
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

1 components:
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

1 components:
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

1 components:
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

1 components:
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.

asyncapi.yml

1 components:
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

1 components:
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

1 components:
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

1 components:
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

1 components:
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

1 components:
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.

1	components:
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'

1	components:
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

1	components:
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

1	components:
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

1	components:
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"

1	components:
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'