Project: CloudEvents (App Definition and Development / Streaming & Messaging)
File: amqp-protocol-binding.md

The AMQP Protocol Binding for CloudEvents defines how events are mapped to OASIS AMQP 1.0 (; ISO/IEC 19464:2014) messages. 1.1. 1.2. 1.3. 1.4. 1.5. 3.2. 3.1. is a standardized and protocol-agnostic definition of the structure and metadata description of events. This specification defines how the elements defined in the CloudEvents specification are to be used in messages. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in . This specification does not prescribe rules constraining transfer or settlement of event messages with AMQP; it solely defines how CloudEvents are expressed as AMQP 1.0 messages. AMQP-based messaging and eventing infrastructures often provide higher-level programming-level abstractions that do not expose all AMQP protocol elements, or map AMQP protocol elements or names to proprietary constructs. This specification uses AMQP terminology, and implementers can refer to the respective infrastructure's AMQP documentation to determine the mapping into a programming-level abstraction. This specification assumes use of the default AMQP [message format][message-format]. The CloudEvents specification defines three content modes for transferring events: structured, binary and batch. The AMQP protocol binding does not currently support the batch content mode. Every compliant implementation SHOULD support both structured and binary modes. In the structured content mode, event metadata attributes and event data are placed into the AMQP message's section using an event format as defined in the CloudEvents . In the binary content mode, the value of the event `data` is placed into the AMQP message's section as-is, with the `datacontenttype` attribute value declaring its media type mapped to the AMQP `content-type` message property; all other event attributes are mapped to the AMQP section. Event formats, used with the structured content mode, define how an event is expressed in a particular data format. All implementations of this specification that support the structured content mode MUST support the [JSON event format][json-format]. This specification does not introduce any new security features for AMQP, or mandate specific existing features to be used. This specification does not further define any of the event attributes. One event attribute, `datacontenttype` is handled specially in binary content mode and mapped onto the AMQP content-type message property. All other attributes are transferred as metadata without further interpretation. This mapping is intentionally robust against changes, including the addition and removal of event attributes, and also accommodates vendor extensions to the event metadata. Any mention of event attributes other than `datacontenttype` is exemplary. The content mode is chosen by the sender of the event, which is either the requesting or the responding party. Protocol interaction patterns that might allow solicitation of events using a particular content mode might be defined by an application, but are not defined here. The receiver of the event can distinguish between the two modes by inspecting the `content-type` message property

If the value is prefixed with the CloudEvents media type `application/cloudevents` (matched case-insensitively), indicating the use of a known , the receiver uses structured mode, otherwise it defaults to binary mode. If a receiver detects the CloudEvents media type, but with an event format that it cannot handle, for instance `application/cloudevents+avro`, it MAY still treat the event as binary and forward it to another party as-is. When the `content-type` message property is not prefixed with the CloudEvents media type, being able to know when the message ought to be attempted to be parsed as a CloudEvent can be a challenge. While this specification can not mandate that senders do not include any of the CloudEvents message properties when the message is not a CloudEvent, it would be reasonable for a receiver to assume that if the message has all of the mandatory CloudEvents attributes as message properties then it's probably a CloudEvent. However, as with all CloudEvent messages, if it does not adhere to all of the normative language of this specification then it is not a valid CloudEvent. The binary content mode accommodates any shape of event data, and allows for efficient transfer and without transcoding effort. For the binary mode, the AMQP `content-type` property field value maps directly to the CloudEvents `datacontenttype` attribute. Event data is assumed to contain opaque application data that is encoded as declared by the `datacontenttype` attribute. An application is free to hold the information in any in-memory representation of its choosing, but as it is transposed into AMQP as defined in this specification, the assumption is that the event data is made available as a sequence of bytes. The byte sequence is used as the AMQP section. Example: If the declared `datacontenttype` is `application/json;charset=utf-8`, the expectation is that the event data is made available as encoded JSON text for use in AMQP. All attributes with exception of `datacontenttype` MUST be individually mapped to and from the AMQP section. CloudEvents extensions that define their own attributes MAY define a secondary mapping to AMQP properties for those attributes, also in different message sections, especially if specific attributes or their names need to align with AMQP features or with other specifications that have explicit AMQP header bindings. However, they MUST also include the previously defined primary mapping. An extension specification that defines a secondary mapping rule for AMQP, and any revision of such a specification, MUST also define explicit mapping rules for all other protocol bindings that are part of the CloudEvents core at the time of the submission or revision. CloudEvent attributes MUST be prefixed with either "cloudEvents_" or "cloudEvents:" for use in the application-properties section. The '\_' separator character SHOULD be preferred in the interest of compatibility with JMS 2.0 clients and JMS message selectors where the ':' separator is not permitted for property identifiers (see section 3.8.1.1 of

Any single message MUST use the same separator for all CloudEvents attributes, but a single queue MAY contain messages which use different separators. CloudEvents AMQP consumers SHOULD understand the "cloudEvents" prefix with both the '\_' and the ':' separators as permitted within the constraints of the client model. JMS 2.0 AMQP consumers MUST understand the '\_' separator; they cannot understand the ':' separator as per the cited JMS constraints. Examples: `time` maps to `cloudEvents_time` `id` maps to `cloudEvents_id` `specversion` maps to `cloudEvents_specversion` The value for each AMQP application property is constructed from the respective attribute's AMQP type representation. The CloudEvents type system MUST be mapped to AMQP types as follows, with additional notes below. | CloudEvents | AMQP | | - | | | Boolean | | | Integer | | | String | | | Binary | | | URI | | | URI-reference | | | Timestamp | | All attribute values in an AMQP binary message MUST either be represented using the native AMQP types above or the canonical string form. An implementation MUST be able to interpret both forms on an incoming AMQP message MAY further relax the requirements for incoming messages (for example accepting numeric types other than AMQP long), but MUST be strict for outgoing messages. SHOULD use the native AMQP form on outgoing AMQP messages when it is efficient to do so, but MAY forward values as canonical strings This example shows the binary mode mapping of an event into the [bare message][message-format] sections of AMQP: ```text properties to: myqueue content-type: application/json; charset=utf-8 -- application-properties -- cloudEvents:specversion: 1.0 cloudEvents:type: com.example.someevent cloudEvents:time: 2018-04-05T03:56:24Z cloudEvents:id: 1234-1234-1234 cloudEvents:source: /mycontext/subcontext .... further attributes ... application-data { ... application data ... } ``` The structured content mode keeps event metadata and data together in the payload, allowing simple forwarding of the same event across multiple routing hops, and across multiple protocols. The property field is set to the media type of an . Example for the : ```text content-type: application/cloudevents+json; charset=UTF-8 ``` The chosen defines how all attributes and `data` are represented. The event metadata and data is then rendered in accordance with the event format specification and the resulting data becomes the AMQP application section. Implementations MAY include the same AMQP application-properties as defined for the . This example shows a JSON event format encoded event: ```text properties to: myqueue content-type: application/cloudevents+json; charset=utf-8 -- application-properties - application-data -- { "specversion" : "1.0", "type" : "com.example.someevent", ... further attributes omitted ... "data" : { ... application data ... } } ``` Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types Key words for use in RFCs to Indicate Requirement Levels UTF-8, a transformation format of ISO 10646 The application/json Media Type for JavaScript Object Notation (JSON) The JavaScript Object Notation (JSON) Data Interchange Format OASIS Advanced Message Queuing Protocol (AMQP) Version 1.0 JSR-343 Java Message Service 2.0