The AMQP type system defines a set of commonly used primitive types used for interoperable data representation. AMQP values may be annotated with additional semantic information beyond that associated with the primitive type. This allows for the association of an AMQP value with an external type that is not present as an AMQP primitive. For example, a URL is commonly represented as a string, however not all strings are valid URLs, and many programming languages and/or applications define a specific type to represent URLs. The AMQP type system would allow for the definition of a code with which to annotate strings when the value is intended to represent a URL.
The following primitive types are defined:
The primitive types defined by AMQP can directly represent many of the basic types present in most popular programming languages, and therefore may be trivially used to exchange basic data. In practice, however, even the simplest applications have their own set of custom types used to model concepts within the application's domain, and, for messaging applications, these custom types need to be externalized for transmission.
AMQP provides a means to do this by allowing any AMQP type to be annotated with a descriptor. A descriptor forms an association between a custom type, and an AMQP type. This association indicates that the AMQP type is actually a representation of the custom type. The resulting combination of the AMQP type and its descriptor is referred to as a described type.
A described type contains two distinct kinds of type information. It identifies both an AMQP type and a custom type (as well as the relationship between them), and so can be understood at two different levels. An application with intimate knowledge of a given domain can understand described types as the custom types they represent, thereby decoding and processing them according to the complete semantics of the domain. An application with no intimate knowledge can still understand the described types as AMQP types, decoding and processing them as such.
Descriptor values other than symbolic (
The namespace for both symbolic and numeric descriptors is divided into distinct domains.
Each domain has a defined symbol and/or 4 byte numeric id assigned by the AMQP working
group. For numeric ids the assigned domain-id will be equal to the IANA Private Enterprise
Number (PEN) of the requesting organisation (
Descriptors are then assigned within each domain according to the following rules:
<domain>:<name>
(domain-id << 32) | descriptor-id
An AMQP encoded data stream consists of untyped bytes with embedded constructors. The embedded constructor indicates how to interpret the untyped bytes that follow. Constructors can be thought of as functions that consume untyped bytes from an open ended byte stream and construct a typed value. An AMQP encoded data stream always begins with a constructor.
An AMQP constructor consists of either a primitive format code, or a described format code. A primitive format code is a constructor for an AMQP primitive type. A described format code consists of a descriptor and a primitive format-code. A descriptor defines how to produce a domain specific type from an AMQP primitive value.
The descriptor portion of a described format code is itself any valid AMQP encoded value, including other described values. The formal BNF for constructors is given below.
Format codes map to one of four different categories: fixed width, variable width, compound and array. Values encoded within each category share the same basic structure parameterized by width. The subcategory within a format-code identifies both the category and width.
The size of fixed-width data is determined based solely on the subcategory of the format code for the fixed width value.
The size of variable-width data is determined based on an encoded size that prefixes the data. The width of the encoded size is determined by the subcategory of the format code for the variable width value.
Compound data is encoded as a size and a count followed by a polymorphic sequence of count constituent values. Each constituent value is preceded by a constructor that indicates the semantics and encoding of the data that follows. The width of the size and count is determined by the subcategory of the format code for the compound value.
Array data is encoded as a size and count followed by an array element constructor followed by a monomorphic sequence of values encoded according to the supplied array element constructor. The width of the size and count is determined by the subcategory of the format code for the array.
The bits within a format code may be interpreted according to the following layout:
The following table describes the subcategories of format-codes:
Please note, unless otherwise specified, AMQP uses network byte order for all numeric values.
The width of a specific fixed width encoding may be computed from the subcategory of the format code for the fixed width value:
Represents an approximate point in time using the Unix time_t encoding of UTC, but with a precision of milliseconds. For example, 1311704463521 represents the moment 2011-07-26T18:21:03.521Z.
All variable width encodings consist of a size in octets followed by size octets of encoded data. The width of the size for a specific variable width encoding may be computed from the subcategory of the format code:
A string represents a sequence of unicode characters as defined by the Unicode V6.0.0 standard (see http://www.unicode.org/versions/Unicode6.0.0).
Symbols are values from a constrained domain. Although the set of possible domains is open-ended, typically the both number and size of symbols in use for any given application will be small, e.g. small enough that it is reasonable to cache all the distinct values.
All compound encodings consist of a size and a count followed by count encoded items. The width of the size and count for a specific compound encoding may be computed from the category of the format code:
A map is encoded as a compound value where the constituent elements form alternating key value pairs.
Map encodings must contain an even number of items (i.e. an equal number of keys and values). A map in which there exist two identical key values is invalid. Unless known to be otherwise, maps must be considered to be ordered - that is the order of the key-value pairs is semantically important and two maps which are different only in the order in which their key-value pairs are encoded are not equal.
All array encodings consist of a size followed by a count followed by an element constructor followed by count elements of encoded data formated as required by the element constructor:
AMQP defines a number of composite types used for encoding structured data such as frame bodies. A composite type describes a composite value where each constituent value is identified by a well known named field. Each composite type definition includes an ordered sequence of fields, each with a specified name, type, and multiplicity. Composite type definitions also include one or more descriptors (symbolic and/or numeric) for identifying their defined representations.
Composite types are formally defined in the XML documents included with the specification. The following notation is used to define them:
An example composite type.
The mandatory attribute of a field description controls whether a null element value is permitted in the representation.
The multiple attribute of a field description controls whether multiple element values are permitted in the representation. A single element of the type specified in the field description is always permitted. Multiple values are represented by the use of an array where the type of the elements in the array is the type defined in the field definition. Note that a null value and a zero-length array (with a correct type for its elements) both describe an absence of a value and should be treated as semantically identical.
A field which is defined as both multiple and mandatory MUST contain at least one value (i.e. for such a field both null and an array with no entries are invalid).
AMQP composite values are encoded as a described list. Each element in the list is positionally correlated with the fields listed in the composite type definition. The permitted element values are determined by the type specification and multiplicity of the corresponding field definitions. When the trailing elements of the list representation are null, they MAY be omitted. The descriptor of the list indicates the specific composite type being represented.
The described list shown below is an example composite value of the book type defined above. A trailing null element corresponding to the absence of an ISBN value is depicted in the example, but may optionally be omitted according to the encoding rules.