The AMQP type system defines a set of commonly used primitive types for interoperable data representation. AMQP values can 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 AMQP type system defines a standard set of primitive types for representing both common scalar values and common collections. The scalar types include booleans, integral numbers, floating point numbers, timestamps, UUIDs, characters, strings, binary data, and symbols. The collection types include arrays (monomorphic), lists (polymorphic), and maps.

The primitive types defined by AMQP can directly represent many of the basic types present in most popular programming languages, and therefore can 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. In 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.

AMQP defines a number of composite types used for encoding structured data such as frame bodies. A composite type defines 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 using the XML notation defined in section 1.3.

AMQP defines the notion of a restricted type. This is a new type derived from an existing type where the permitted values of the new type are a subset of the values of the existing type. Restricted types are commonly used programming constructs, the most frequent being "enumerations" which in AMQP terminology are restrictions of the integral types. However, the AMQP notion of restricted types can also represent more open ended restrictions such as a URL which can be thought of as a restriction of the string type.

A restricted type definition might limit the permitted values to either a pre-defined fixed set, or an open-ended set. In the former case, each permitted value is called a choice and all possible choices are listed in the formal type definition. In the latter case, the nature of the restriction is specified as text in the formal type definition.

The existing type from which a restricted type is derived is referred to as the source type for the restriction. A restricted type might or might not be annotated with a descriptor on the wire depending on the formal definition for the type.

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.

Fixed Width

The size of fixed-width data is determined based solely on the subcategory of the format code for the fixed width value.

Variable Width

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

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

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 can 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 can be computed from the subcategory of the format code for the fixed width value:

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 can be computed from the subcategory of the format code:

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 can be computed from the category of the format code:

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:

Types are formally specified using an XML notation described below. Please note that this XML notation is used only to define the type and is never used to represent encoded data. All encoded AMQP data is binary as described in section 1.2.

The type element formally defines a semantic type used to exchange data on the wire. Every type definition has the following general form. The child elements present depend upon the class of the type definition (primitive, composite, or restricted):

The attributes of a type definition specify the following:

name

The name of the type.

label

A short description of the type.

class

A string identifying what class of type is being defined: "primitive", "composite", or "restricted".

provides

A comma separated list of archetypes (see field element).

There are three different classes of types identified by the "class" attribute: primitive, composite, and restricted.

A "primitive" type definition will contain one or more encoding elements that describe how the data is formatted on the wire. Primitive types do not contain the descriptor, field, or choice elements.

The encoding element defines how a primitive type is encoded. The specification defines 4 general categories of encodings: fixed, variable, compound, and array. A specific encoding provides further details of how data is formatted within its general category.

name

The name of the encoding.

label

A short description of the encoding.

code

The numeric value that prefixes the encoded data on the wire.

category

The category of the encoding: "fixed", "variable", "compound", or "array".

width

The width of the encoding or the size/count prefixes depending on the category.

A "composite" type definition specifies a new kind of record type, i.e., a type composed of a fixed number of fields whose values are each of a specific type. A composite type does not have a new encoding, but is sent on the wire as a list annotated by a specific descriptor value that identifies it as a representation of the defined composite type. A composite type definition will contain a descriptor and zero or more field elements. Composite types do not contain encoding or choice elements. The source attribute of a composite type will always be "list", other values are reserved for future use.

The descriptor element specifies what annotation is used to identify encoded values as representations of a described type.

name

A symbolic name for the representation.

code

The numeric value.

The field element identifies a field within a composite type. Every field has the following attributes:

name

A name that uniquely identifies the field within the type.

type

The type of the field. This attribute defines the range of values that are permitted to appear in this field. It might name a specific type, in which case the values are restricted to that type, or it might be the special character "*", in which case a value of any type is permitted. In the latter case the range of values might be further restricted by the requires attribute.

requires

A comma separated list of archetypes. Field values are restricted to types providing at least one of the specified archetypes.

default

A default value for the field if no value is encoded.

label

A short description of the field.

mandatory

"true" iff a non null value for the field is always encoded.

multiple

"true" iff the field can have multiple values of its specified type.

A "restricted" type definition specifies a new kind of type whose values are restricted to a subset of the values that might be represented with another type. The source attribute identifies the base type from which a restricted type is derived. A restricted type can have a descriptor element in which case it is identified by a descriptor on the wire. The values permitted by a restricted type can be specified either via documentation, or directly limited to a fixed number of values by the choice elements contained within the definition.

The choice element identifies a legal value for a restricted type. The choice element has the following attributes:

name

A name for the value.

value

The permitted value.

AMQP composite types are represented 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 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 MUST 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).

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 can optionally be omitted according to the encoding rules.

Descriptor values other than symbolic (symbol) or numeric (ulong) are, while not syntactically invalid, reserved - this includes numeric types other than ulong. To allow for users of the type system to define their own descriptors without collision of descriptor values, an assignment policy for symbolic and numeric descriptors is given below.

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 [IANAPEN] with domain-id 0 reserved for descriptors defined in the AMQP specification.

Descriptors are then assigned within each domain according to the following rules:

symbolic descriptors

<domain>:<name>

numeric descriptors

(domain-id << 32) | descriptor-id

A 32-bit floating point number (IEEE 754-2008 binary32 [IEEE754]).

A 64-bit floating point number (IEEE 754-2008 binary64 [IEEE754]).

A 32-bit decimal number (IEEE 754-2008 decimal32 [IEEE754]).

A 64-bit decimal number (IEEE 754-2008 decimal64 [IEEE754]).

A 128-bit decimal number (IEEE 754-2008 decimal128 [IEEE754]).

A UTF-32BE encoded Unicode character [UNICODE6].

Represents an approximate point in time using the Unix time_t [IEEE1003] encoding of UTC, but with a precision of milliseconds. For example, 1311704463521 represents the moment 2011-07-26T18:21:03.521Z.

UUID is defined in section 4.1.2 of RFC-4122 [RFC4122].

A string represents a sequence of Unicode characters as defined by the Unicode V6.0.0 standard [UNICODE6].

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. Symbols are encoded as ASCII characters [ASCII].

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.