AsyncAPI Message Payloads — Complete Guide
In this tutorial, you will learn about AsyncAPI Message Payloads. We cover key concepts, practical examples, and best practices to help you master this topic.
Message payloads carry the actual business data in AsyncAPI events. Choosing the right schema format and designing payloads carefully ensures compatibility, evolvability, and clear contracts between services.
What You'll Learn
- JSON Schema payload definitions
- Avro schema integration
- Schema evolution and backward compatibility
- Multiple schema format support
- Payload validation techniques
Why It Matters
The payload is the most important part of a message. Poorly designed payloads lead to breaking changes, data loss, and integration issues when schemas evolve.
Real-World Use
A streaming analytics platform uses Avro schemas for all AsyncAPI messages. When the schema evolves (adding optional fields), the schema registry ensures backward compatibility, and consumers continue working without code changes.
Flow Chart
flowchart LR
A[Message Payload] --> B{Schema Format}
B --> C[JSON Schema]
B --> D[Avro]
B --> E[Protobuf]
B --> F[Custom]
C --> G[.json]
D --> H[.avsc]
E --> I[.proto]
F --> J[.xml/.yaml]
G --> K[Validation]
H --> K
I --> K
K --> L[Compatible?]
L -->|Yes| M[Accept]
L -->|No| N[Reject]
Code Examples
Example 1: JSON Schema Payload
components:
schemas:
OrderPayload:
type: object
required:
- orderId
- customerId
- items
- total
properties:
orderId:
type: string
description: Unique order identifier
pattern: '^ORD-[0-9]{8}$'
customerId:
type: string
format: uuid
items:
type: array
minItems: 1
items:
$ref: '#/components/schemas/OrderItem'
total:
type: number
minimum: 0
exclusiveMinimum: true
currency:
type: string
default: USD
enum: [USD, EUR, GBP, JPY]
createdAt:
type: string
format: date-time
messages:
OrderPlaced:
payload:
$ref: '#/components/schemas/OrderPayload'
Expected output: A JSON Schema payload with validation rules, enums, patterns, and references to nested schemas.
Example 2: Avro Schema Payload
channels:
user/events:
publish:
message:
schemaFormat: 'application/vnd.apache.avro+json'
payload:
type: record
name: UserEvent
namespace: com.example.events
doc: User lifecycle events
fields:
- name: eventId
type: string
doc: Unique event identifier
- name: userId
type: string
- name: eventType
type:
type: enum
name: UserEventType
symbols:
- CREATED
- UPDATED
- DELETED
- name: timestamp
type:
type: long
logicalType: timestamp-millis
- name: userData
type:
type: record
name: UserData
fields:
- name: email
type: string
- name: displayName
type: [string, null]
default: null
Expected output: An Avro schema payload with complex types, enums, logical types, and union types for nullable fields.
Example 3: Payload with Multiple Schema Versions
channels:
order/events:
publish:
message:
oneOf:
- $ref: '#/components/messages/OrderEventV1'
- $ref: '#/components/messages/OrderEventV2'
components:
messages:
OrderEventV1:
name: OrderEventV1
payload:
type: object
properties:
orderId:
type: string
status:
type: string
OrderEventV2:
name: OrderEventV2
payload:
type: object
properties:
orderId:
type: string
status:
type: string
customerEmail:
type: string
description: Added in v2
items:
type: array
items:
type: object
properties:
productId:
type: string
quantity:
type: integer
Expected output: A channel that supports multiple schema versions using oneOf, allowing gradual migration from v1 to v2.
Common Mistakes
| Mistake | Explanation |
|---|---|
| Making all fields required | Required fields make schema evolution difficult; mark new fields as optional |
| Ignoring field types | Always specify precise types (string, integer, number) instead of using generic formats |
| Not documenting nullable fields | Use union types or nullable: true to explicitly mark optional fields |
| Forgetting backward compatibility | Removing fields or making optional fields required breaks existing consumers |
| Mixing schema formats inconsistently | Choose one primary format and use it consistently across all messages |
| Overly nested payloads | Deep nesting makes payloads hard to read and Process; flatten where possible |
Practice Questions
- What are the advantages of Avro over JSON Schema for event payloads?
- How do you handle optional fields in JSON Schema payloads?
- What is schema evolution and why is it important?
- How does the
schemaFormatfield affect Code Generation? - What strategies can you use to version payloads?
Challenge
Design a customer profile event payload that evolves through three versions. Start with basic fields (id, name, email), add address in v2, and add preferences in v3. Ensure each version is backward compatible with the previous one.
FAQ
Mini Project
Design a complete payload schema library for a social media platform. Include schemas for user profiles, posts, comments, likes, and notifications. Use JSON Schema with proper validation, examples, and backward-compatible evolution Strategy.
What's Next
Learn about server definitions in AsyncAPI
Built by the developers of DodaTech
Doda Browser, DodaZIP & Durga Antivirus Pro