CloudEvents is a specification for describing event data in common formats to provide interoperability across services, platforms and systems.1
This document clarifies how CloudEvents can be specified in AsyncAPI.
Usage
Depending on the protocol and the mode (binary/structured), the inclusion of the CloudEvents fields varies.
Structured Mode
In structured mode, the entire event, attributes, and data are encoded in the message body. When using structured mode, the usage only varies depending on the serialization format:
| Format | Example | Include |
|---|---|---|
| JSON | Short Example Full Example | Reference |
JSON Example
To add CloudEvents in structured mode, the following allOf reference needs to
be added:
1components:
2 messages:
3 messageKey:
4 payload:
5 type: object
6 allOf:
7 - $ref: 'https://raw.githubusercontent.com/cloudevents/spec/v1.0.2/cloudevents/formats/cloudevents.json'See also: Full Example
Binary Mode
In binary mode, protocol-specific bindings are mapping fields to protocol content-type metadata property or headers; therefore, the AsyncAPI format needs to depend on the protocol:
| Protocol Binding | Example | Trait |
|---|---|---|
| Kafka | Short Example Full Example | Trait |
Avro Example
To add CloudEvents in binary mode, the following traits reference needs to
be added:
1components:
2 messages:
3 messageKey:
4 traits:
5 - $ref: 'https://raw.githubusercontent.com/cloudevents/spec/main/cloudevents/working-drafts/asyncapi-traits/cloudevents-headers-kafka-binary.yaml'See also: Full Example
