AMP Argument Types

Values in AMP are strongly, statically typed. This is a good thing.

The standard types are defined below, however you may also define arbitrary types with a serialization
format of your choosing. Provided, of course, that both sides of the connection can handle them.

Maximum Encoded Size

As per the AMP wire protocol, individual values cannot exceed 65,535 bytes in their final encoded form.

The Standard Types

The following types are shipped with the reference implementation using the names given here. However
other implementations may use different names for the same types, e.g. "Bytes" instead of "String".

Other implementations may, or may not, provide all of these types, however it shouldn't be too difficult to
implement missing ones yourself.

Basic Types

These are the basic AMP value types.

Integer

Integers are encoded as their base-10 string (UTF-8, of course) representations, e.g. "123" or "-20".

AMP does not impose any restriction on the range of integer values, but specific implementations may
impose restrictions depending on how integers are stored in the implementation language.

String

A sequence of bytes. It should have been called Bytes. (e.g. a C# byte[] or a Python 2.x str object).

Values are placed on the wire just as they are; no encoding necessary.

Unicode

A sequence of Unicode code-points. (e.g a C# string or a Python 2.x unicode object).

Encoded on the wire in UTF-8.

Boolean

A truth value.

Encoded as either the string "True", or "False".

Float

A hardware-precision floating-point value. (e.g. a C# double or a Python float).

Encoded as a string, e.g. "123", "10.", or "-123.40000000000001".

AMP places no restriction on the range of valid floating-point values, however specific implementations
may impose restrictions depending on how floats are stored in the underlying language.

Special values are encoded as special strings:

• Positive infinity is encoded as "inf".

• Negative infinity is encoded as "-inf".

• Not-a-number is encoded as "nan".

Decimal

An exact-precision decimal number. (e.g. a C# decimal or a Python decimal.Decimal object).

Special values are encoded as special strings:

• Positive infinity is encoded as "Infinity".

• Negative infinity is encoded as "-Infinity".

• Quiet not-a-number is encoded as either "NaN" or "-NaN".

• Signaling not-a-number is encoded as either "sNaN" or "-sNaN".

Normal values are encoded using the base ten string representation, using engineering notation to indicate
magnitude without precision, and "normal" digits to indicate precision. For example:

• "1" represents the value 1 with precision to one place.

• "-1" represents the value -1 with precision to one place.

• "1.0" represents the value 1 with precision to two places.

• "10" represents the value 10 with precision to two places.

• "1E+2" represents the value 10 with precision to one place.

• "1E-1" represents the value 0.1 with precision to one place.

• "1.5E+2" represents the value 15 with precision to two places.

DateTime

An exact wall-clock date and time.

Encoded as a UTF-8 string according to the following format:

• %04i-%02i-%02iT%02i:%02i:%02i.%06i%s%02i:%02i

Fields, in order, are:

• year (1-9999)
• month (1-12)
• day (1-31)
• hour (0-23)
• minute (0-59)
• second (0-59)
• microsecond (0-999999)
• timezone direction (+ or -)
• timezone hour (0-23)
• timezone minute (0-59)

The encoded string is always exactly 32 characters long. This format is compatible
with ISO 8601, but that does not mean all ISO 8601 dates can be accepted.

The timezone fields give the offset from UTC of the Time Zone that the DateTime
falls in to. An AMP DateTime does not encode Day Light Savings information - such
information should be transferred separately if needed.

Example: "1969-08-15T12:00:00.000000+00:00"
Example: "2012-01-23T12:34:56.054321-01:23"

Compound Types

These are rich types that may encoded more than one object in to a single "AMP value".

ListOf

A sequence of another AMP Type. E.g. ListOf(Integer). All objects in the list must be of the same type.
Arbitrary nesting is allowed so you could have e.g. ListOf(ListOf(String)) for a 2-D "matrix" of strings.

For each object, its encoded size is calculated and placed on the wire as a 16-bit (big-endian) value,
directly followed by the encoded data for that particular object. The encoded data for each object is
calculated following the rules for the AMP Type of the list.

As always, the total encoded size of all prefix values and objects may not exceed 65,535 bytes.

AmpList

A sequence of AMP messages that follow a common schema. An AMP message is just a set of key/value
pairs that follow the normal rules for keys and values in AMP. For example, is pseudo-code you might
define an AmpList like this:

MyAmpList:
    "foo" => Integer()
    "bar" => String()
    "baz" => ListOf(Float())

Then arguments of this type would contain zero or more "messages" (dictionaries), each with a "foo",
"bar" and "baz" key. Values conform to the given types, in this case Integer, String and ListOf(Float).
Any value types supported by your AMP implementation may be used. As with ListOf, arbitrary nesting is
allowed, so a value in your AmpList could contain another AmpList with a different key/value schema.

An AmpList value is encoded as follows. Each message in the sequence is encoded and placed on the wire,
one after the other. A message (collection of key/value pairs), is encoded following the
normal AMP protocol rules.

That is, the key length is encoded as a 16-bit big-endian value and placed on the wire, followed by the bytes
that make up the key name. As normal, keys may not be longer than 255 bytes. Then the value length is
encoded as a 16-bit big-endian value and placed on the wire, followed by the encoded bytes that make up
the value. The message is terminated with an empty key (2 NUL bytes).