Messages and Payloads
Document async API messages with payload schemas, headers, correlation IDs, protocol bindings, and realistic examples. Apply message traits for cross-cutting concerns.
Messages define the structure and semantics of data exchanged through async API channels. Each message documents its payload schema, headers, correlation mechanism, protocol-specific bindings, and concrete examples.
Message Structure
| Property | Description |
|---|---|
| Name | Message identifier (e.g. OrderCreatedEvent) |
| Payload Schema | Reference to a schema definition that describes the message body |
| Content Type | MIME type of the payload (JSON, Avro, Protobuf, XML, Binary, Plain Text, CloudEvents) |
| Headers Schema | Reference to a schema definition for message headers |
| Correlation ID | Expression for extracting the correlation identifier from the message |
| Protocol Bindings | Protocol-specific message properties (Kafka key schema, AMQP encoding, etc.) |
| Examples | Concrete JSON examples with headers and payload |
| Traits | Reusable message traits for cross-cutting header and binding patterns |
| Deprecated | Mark messages as deprecated with migration guidance |
Payload Schemas
Message payloads reference schemas defined in the Schema Editor. This keeps message structures consistent with your data model and enables end-to-end data lineage from event payloads to database entities.
Example: Order Event Payload Schema
Example: Shared Event Headers Schema
Correlation IDs
Correlation IDs enable distributed tracing across services. Each message can define a correlation ID with a location expression that tells consumers where to find the identifier.
{
"correlationId": {
"description": "UUID correlation identifier propagated across service boundaries",
"location": "$message.header#/correlationId"
}
}Message Examples
Each message can include multiple examples with name, summary, headers JSON, and payload JSON. Examples are displayed with syntax highlighting in the published viewer.
Order Created Event
Payment Processed Event
Inventory Updated Event
Message Traits
Message traits define reusable cross-cutting properties that apply to multiple messages. Common use cases include standard headers for correlation, auditing, and CloudEvents envelopes.
| Trait Property | Description |
|---|---|
| Headers Schema | Shared header schema applied to all messages using this trait |
| Correlation ID | Standard correlation ID configuration |
| Content Type | Default content type override |
| Protocol Bindings | Shared protocol-specific message bindings |
| Tags | Categorisation tags inherited by messages |
Supported Content Types
| Content Type | Use Case |
|---|---|
| application/json | Standard JSON payloads (most common) |
| application/avro | Apache Avro serialised messages (with Schema Registry) |
| application/protobuf | Protocol Buffers serialised messages |
| application/xml | XML-formatted messages |
| application/octet-stream | Binary payloads |
| text/plain | Plain text messages |
| application/cloudevents+json | CloudEvents JSON envelope format |