2. Simple types#

Simple types are types that do not contain nested types or shape references.

2.1. blob#

A blob is uninterpreted binary data.

blob MyBlob

2.2. boolean#

A boolean is a Boolean value type.

boolean MyBoolean

2.3. string#

A string is a UTF-8 encoded string.

string MyString

2.4. byte#

A byte is an 8-bit signed integer ranging from -128 to 127 (inclusive).

byte MyByte

2.5. short#

A short is a 16-bit signed integer ranging from -32,768 to 32,767 (inclusive).

short MyShort

2.6. integer#

An integer is a 32-bit signed integer ranging from -2^31 to (2^31)-1 (inclusive).

integer MyInteger

2.7. long#

A long is a 64-bit signed integer ranging from -2^63 to (2^63)-1 (inclusive).

long MyLong

2.8. float#

A float is a single precision IEEE-754 floating point number.

float MyFloat

2.9. double#

A double is a double precision IEEE-754 floating point number.

double MyDouble

2.10. bigInteger#

A bigInteger is an arbitrarily large signed integer.

bigInteger MyBigInteger

2.11. bigDecimal#

A bigDecimal is an arbitrary precision signed decimal number.

bigDecimal MyBigDecimal

2.12. timestamp#

A timestamp represents an instant in time in the proleptic Gregorian calendar, independent of local times or timezones. Timestamps support an allowable date range between midnight January 1, 0001 CE to 23:59:59.999 on December 31, 9999 CE, with a temporal resolution of 1 millisecond. This resolution and range ensures broad support across programming languages and guarantees compatibility with RFC 3339.

timestamp MyTimestamp

2.12.1. Timestamp serialization and deserialization#

The serialization format of a timestamp is an implementation detail that is determined by a protocol and or timestampFormat trait. The format of a timestamp MUST NOT have any effect on the types exposed by tooling to represent a timestamp value.

Protocols and timestampFormat traits MAY support temporal resolutions other than 1 millisecond. For example, the http-date timestamp format supports only seconds and forbids fractional precision. Modelers need to be aware of these limitations when defining timestamps to avoid an unintended loss of precision.

The use of timestamps outside the allowable range risk not interoperating correctly across Smithy implementations; deserializers that encounter timestamps outside the allowable range SHOULD fail to deserialize the value.

2.13. document#

A document represents protocol-agnostic open content that functions as a kind of "any" type. Document types are represented by a JSON-like data model and can contain UTF-8 strings, arbitrary precision numbers, booleans, nulls, a list of these values, and a map of UTF-8 strings to these values. Open content is useful for modeling unstructured data that has no schema, data that can't be modeled using rigid types, or data that has a schema that evolves outside of the purview of a model. The serialization format of a document is an implementation detail of a protocol and MUST NOT have any effect on the types exposed by tooling to represent a document value.

document MyDocument

2.14. enum#

The enum shape is used to represent a fixed set of one or more string values. Each value listed in the enum is a member that implicitly targets the unit type.

The following example defines an enum shape:

enum Suit {
    DIAMOND
    CLUB
    HEART
    SPADE
}

The following example is exactly equivalent to the previous example, but the enum values are made explicit:

enum Suit {
    DIAMOND = "DIAMOND"
    CLUB = "CLUB"
    HEART = "HEART"
    SPADE = "SPADE"
}

2.14.1. enum values#

The value of an enum member can be customized by applying the enumValue trait. If an enum member doesn't have an explicit enumValue trait, an enumValue trait is implicitly added to the member with the trait value set to the member's name.

The following example provides custom enum values for each member using syntactic sugar in the Smithy IDL:

enum Suit {
    DIAMOND = "diamond"
    CLUB = "club"
    HEART = "heart"
    SPADE = "spade"
}

The above example is exactly equivalent to the following:

enum Suit {
    @enumValue("diamond")
    DIAMOND

    @enumValue("club")
    CLUB

    @enumValue("heart")
    HEART

    @enumValue("spade")
    SPADE
}

2.14.2. enum is a specialization of string#

Enums are considered open, meaning it is a backward compatible change to add new members. Previously generated clients MUST NOT fail when they encounter an unknown enum value. Client implementations MUST provide the capability of sending and receiving unknown enum values.

2.14.3. enum validation#

  • Enums do not support aliasing; all values MUST be unique.
  • Enum member names SHOULD NOT contain any lowercase ASCII Latin letters (a-z) and SHOULD NOT start with an ASCII underscore (_). That is, enum names SHOULD match the following regular expression: ^[A-Z]+[A-Z_0-9]*$.

2.15. intEnum#

An intEnum is used to represent an enumerated set of one or more integer values. The members of intEnum MUST be marked with the enumValue trait set to a unique integer value. Syntactic sugar in the Smithy IDL can be used to apply the enumValue trait. Each value of an intEnum is a member that implicitly targets the unit type.

The following example defines an intEnum shape using Smithy IDL syntactic sugar:

intEnum FaceCard {
    JACK = 1
    QUEEN = 2
    KING = 3
    ACE = 4
    JOKER = 5
}

The above example is exactly equivalent to the following:

intEnum FaceCard {
    @enumValue(1)
    JACK

    @enumValue(2)
    QUEEN

    @enumValue(3)
    KING

    @enumValue(4)
    ACE

    @enumValue(5)
    JOKER
}

2.15.1. intEnum is a specialization of integer#

intEnums are considered open, meaning it is a backward compatible change to add new members. Previously generated clients MUST NOT fail when they encounter an unknown intEnum value. Client implementations MUST provide the capability of sending and receiving unknown intEnum values.

2.15.2. intEnum validation#

  • intEnums do not support aliasing; all values MUST be unique.
  • intEnum member names SHOULD NOT contain any lowercase ASCII Latin letters (a-z) and SHOULD NOT start with an ASCII underscore (_). That is, enum names SHOULD match the following regular expression: ^[A-Z]+[A-Z_0-9]*$.