Skip to content

Latest commit

 

History

History
129 lines (100 loc) · 5.26 KB

amqp-format.md

File metadata and controls

129 lines (100 loc) · 5.26 KB
Raw

AMQP Event Format for CloudEvents - Version 0.3

Abstract

The AMQP Format for CloudEvents defines how event attributes are expressed in the AMQP 1.0 Type System.

Status of this document

This document is a working draft.

Table of Contents

  1. Introduction
  2. Attributes
  3. References

1. Introduction

CloudEvents is a standardized and transport-neutral definition of the structure and metadata description of events. This specification defines how the elements defined in the CloudEvents specification are to be represented in the [AMQP 1.0 Type System][amqp-types].

The Attributes section describes the naming conventions and data type mappings for CloudEvents attributes for use as AMQP message properties.

This specification does not define an envelope format. The AMQP type system's intent is primarily to provide a consistent type system for AMQP itself and not for message payloads.

1.1. Conformance

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 RFC2119.

2. Attributes

This section defines how CloudEvents attributes are mapped to the AMQP type-system. This specification does not explicitly map each attribute, but provides a generic mapping model that applies to all current and future CloudEvents attributes, including extensions.

2.1. Base Type System

The core CloudEvents specification defines a minimal abstract type system, which this mapping leans on.

2.2. Type System Mapping

The CloudEvents type system MUST be mapped to AMQP types as follows, with exceptions noted below.

CloudEvents AMQP
String string
Integer long
Binary binary
URI-reference string
Timestamp timestamp
Map map
Any See 2.3.

A CloudEvents AMQP format implementation MUST allow for attribute values to be convertible from/to their canonical CloudEvents string representation. For instance, the time attribute MUST be convertible from and to a conformant RFC3339 string value.

If an non-string attribute is received as string from a communicating party, an AMQP intermediary MAY convert it to the native AMQP representation before forwarding the event; an AMQP consumer SHOULD convert it to the native AMQP representation before surfacing the value to the API. An AMQP implementation SHOULD convert from/to the native runtime or language type system to the AMQP type system directly without translating through strings whenever possible.

Extension specifications MAY define diverging mapping rules for the values of attributes they define.

For instance, the attribute value may be a data structure defined in a standard outside of CloudEvents, with a formal AMQP mapping, and there might be risk of translation errors or information loss when the original format is not preserved.

An extension specification that defines a diverging mapping rule for AMQP, and any revision of such a specification, MUST also define explicit mapping rules for all other event formats that are part of the CloudEvents core at the time of the submission or revision.

2.3. Mapping Any-typed Attributes

Any-typed CloudEvents values can either hold a String, or a Binary value, or a Map. Map entry values are also Any typed. AMQP's type system natively represents dynamic typing in its type system encoding, and therefore immediately allows for the required variant type representation.

3. References

  • RFC2046 Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types
  • RFC2119 Key words for use in RFCs to Indicate Requirement Levels
  • [OASIS-AMQP-1.0][oasis-amqp-1.0] OASIS Advanced Message Queuing Protocol (AMQP) Version 1.0