Smithy core specification¶

Version compatibility¶

A single version statement can appear in a model file. Different versions MAY be encountered when merging multiple model files together. Multiple versions are supported if and only if all of the version statements are supported by the tool loading the models.

Timestamp serialization format¶

By default, the serialization format of a timestamp is implicitly determined by the protocol of a service; however, the serialization format can be explicitly configured to override the default format used by the protocol by applying the timestampFormat trait to a timestamp shape or a member that targets a timestamp.

The following steps are taken to determine the serialization format of a timestamp:

1. Use the timestampFormat trait of the member reference if present.
2. Use the timestampFormat trait of the shape if present.
3. Use the format required by the protocol.

The timestamp shape is an abstraction of time; the serialization format of a timestamp as it is sent over the wire, whether determined by the protocol or by the timestampFormat trait, SHOULD NOT have any effect on the types exposed by tooling to represent a timestamp.

Document types¶

A document type represents an untyped JSON-like value that can take on one of the following types: null, boolean, string, byte, short, integer, long, float, double, an array of these types, or a map of these types where the key is a string.

Not all protocols support document types, and the serialization format of a document type is protocol-specific. All JSON protocols SHOULD support document types and they SHOULD serialize document types inline as normal JSON values.

list¶

The list type represents a homogeneous collection of values. A list is defined using a list_statement. A list statement consists of the shape named followed by an object with a single key-value pair of "member" that defines the member of the list.

The following example defines a list with a string member from the prelude:

list MyList {
    member: String
}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#MyList": {
            "member": {
                "target": "smithy.api#String"
            }
        }
    }
}

Traits can be applied to the list shape and its member:

@length(min: 3, max: 10)
list MyList {
    @length(min: 1, max: 100)
    member: String
}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#MyList": {
            "member": {
                "target": "smithy.api#String",
                "traits": {
                    "smithy.api#length": {
                        "min": 1,
                        "max": 100
                    }
                }
            },
            "traits": {
                "smithy.api#length": {
                    "min": 3,
                    "max": 10
                }
            }
        }
    }
}

Traits can be applied to shapes and members outside of their definition using an apply statement:

apply MyList @documentation("Long documentation string...")
apply MyList$member @documentation("Long documentation string...")

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#MyList": {
            "type": "apply",
            "traits": {
                "smithy.api#documentation": "Long documentation string..."
            }
        },
        "smithy.example#MyList$member": {
            "type": "apply",
            "traits": {
                "smithy.api#documentation": "Long documentation string..."
            }
        }
    }
}

set¶

The set type represents an unordered collection of unique homogeneous values. A set is defined using a set_statement that consists of the shape named followed by an object with a single key-value pair of "member" that defines the member of the set.

The following example defines a set of strings:

set StringSet {
    member: String
}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#StringSet": {
            "member": {
                "target": "smithy.api#String"
            }
        }
    }
}

Traits can be applied to the set shape and its members:

@deprecated
set StringSet {
    @sensitive
    member: String
}

// Apply additional traits to the set member.
apply StringSet$member @documentation("text")

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#StringSet": {
            "member": {
                "target": "smithy.api#String"
            },
            "traits": {
                "smithy.api#deprecated": true
            }
        },
        "smithy.example#StringSet$member": {
            "type": "apply",
            "traits": {
                "smithy.api#documentation": "text"
            }
        }
    }
}

map¶

The map type represents a map data structure that maps string keys to homogeneous values. A map cannot contain duplicate keys. A map is defined using a map_statement. The key member of a map MUST target a string shape.

The following example defines a map of strings to integers:

map IntegerMap {
    key: String,
    value: Integer
}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#IntegerMap": {
            "key": {
                "target": "smithy.api#String"
            },
            "value": {
                "target": "smithy.api#String"
            }
        }
    }
}

Traits can be applied to the map shape and its members:

@length(min: 0, max: 100)
map IntegerMap {
    @length(min: 1, max: 10)
    key: String,

    @sensitive
    value: Integer
}

// Apply more traits to the key and value members.
apply IntegerMap$key @documentation("Key documentation")
apply IntegerMap$value @documentation("Value documentation")

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#IntegerMap": {
            "key": {
                "target": "smithy.api#String",
                "traits": {
                    "smithy.api#length": {
                        "min": 1,
                        "max": 10
                    }
                }
            },
            "value": {
                "target": "smithy.api#String",
                "traits": {
                    "smithy.api#sensitive": true
                }
            },
            "traits": {
                "smithy.api#length": {
                    "min": 0,
                    "max": 100
                }
            }
        },
        "smithy.example#IntegerMap$key": {
            "type": "apply",
            "traits": {
                "smithy.api#documentation": "Key documentation"
            }
        },
        "smithy.example#IntegerMap$value": {
            "type": "apply",
            "traits": {
                "smithy.api#documentation": "Value documentation"
            }
        }
    }
}

structure¶

The structure type represents a fixed set of named heterogeneous members. A member name maps to exactly one structure member definition.

A structure is defined using a structure_statement. A structure statement is a map of structure member names to the shape targeted by the member. Any number of inline traits can precede each member.

The following example defines a structure with two members:

structure MyStructure {
    foo: String,
    baz: Integer,
}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#MyStructure": {
            "type": "structure",
            "members": {
                "foo": {
                    "target": "smithy.api#String"
                },
                "baz": {
                    "target": "smithy.api#Integer"
                }
            }
        }
    }
}

Traits can be applied to members inside of the structure or externally using the apply statement:

structure MyStructure {
    @required
    foo: String,

    @deprecated
    baz: Integer,
}

apply MyStructure$foo @documentation("Documentation content...")

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#MyStructure": {
            "type": "structure",
            "members": {
                "foo": {
                    "target": "smithy.api#String",
                    "traits": {
                        "smithy.api#required": true
                    }
                },
                "baz": {
                    "target": "smithy.api#Integer",
                    "traits": {
                        "smithy.api#deprecated": true
                    }
                }
            }
        },
        "smithy.example#MyStructure$foo": {
            "type": "apply",
            "traits": {
                "smithy.api#documentation": "Documentation content..."
            }
        }
    }
}

union¶

The union type represents a tagged union data structure that can take on several different, but fixed, types. Only one type can be used at any one time.

A union is defined using a union_statement. Union shapes take the same form as structure shapes.

The following example defines a union shape with several members:

union MyUnion {
    i32: Integer,
    stringA: String,
    @sensitive stringB: String,
}

// Apply additional traits to the member named "i32".
apply MyUnion$i32 @documentation("text")

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#MyUnion": {
            "type": "structure",
            "members": {
                "i32": {
                    "target": "smithy.api#Integer"
                },
                "stringA": {
                    "target": "smithy.api#String"
                },
                "stringB": {
                    "target": "smithy.api#String",
                    "traits": {
                        "smithy.api#sensitive": true
                    }
                }
            }
        },
        "smithy.example#MyUnion$i32": {
            "type": "apply",
            "traits": {
                "smithy.api#documentation": "text"
            }
        }
    }
}

member¶

Members are defined in aggregate types to reference other shapes using a shape ID. A member MUST NOT target an operation, resource, service, member, or trait definition.

The following example defines a list shape. The member of the list is a member shape with a shape ID of smithy.example#MyList$member. The member targets the MyString shape in the same namespace.

namespace smithy.example

list MyList {
    member: MyString
}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#MyList": {
            "member": {
                "target": "smithy.example#MyString"
            }
        }
    }
}

Traits can be attached to members before the member definition:

list MyList {
    @sensitive
    member: MyString
}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#MyList": {
            "member": {
                "target": "smithy.example#MyString",
                "traits": {
                    "smithy.api#sensitive": true
                }
            }
        }
    }
}

Traits can be applied to member definitions using the apply statement followed by the targeted shape ID followed by the trait value. Traits are applied to shapes outside of their definition in the JSON AST using the "traits" key-value pair of a namespace.

apply MyList$member @documentation("Hello")

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#MyList$member": {
            "type": "apply",
            "traits": {
                "smithy.api#documentation": "Hello"
            }
        }
    }
}

The shape ID of a member consists of the aggregate shape name followed by "$" followed by the member name. The member name for each shape is defined in Shape ID member names.

list RecursiveList {
    member: RecursiveList
}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#RecursiveList": {
            "type": "list",
            "member": {
                "target": "smithy.example#RecursiveList"
            }
        }
    }
}

list ValidList {
    member: IntermediateStructure
}

structure IntermediateStructure {
    foo: ValidList
}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#ValidList": {
            "type": "list",
            "member": {
                "target": "smithy.example#IntermediateStructure"
            }
        },
        "smithy.example#IntermediateStructure": {
            "type": "structure",
            "members": {
                "foo": {
                    "target": "smithy.example#ValidList"
                }
            }
        }
    }
}

Service¶

A service is the entry point of an API that aggregates resources and operations together. The resources and operations of an API are bound within the closure of a service.

A service shape is defined using a service_statement and supports the following properties:

service MyService {
    version: "2017-02-11",
    operations: [GetServerTime],
}

@readonly
operation GetServerTime {
    output: GetServerTimeOutput
}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#MyService": {
            "type": "service",
            "version": "2017-02-11",
            "operations": [
                {
                    "target": "smithy.example#GetServerTime"
                }
            ]
        },
        "smithy.example#GetServerTime": {
            "type": "operation",
            "output": {
                "target": "smithy.example#GetServerTimeOutput"
            }
        }
    }
}

service MyService {
    version: "2017-02-11",
    resources: [MyResource],
}

resource MyResource {}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#MyService": {
            "type": "service",
            "version": "2017-02-11",
            "resources": [
                {
                    "target": "smithy.example#MyResource"
                }
            ]
        },
        "smithy.example#MyResource": {
            "type": "resource"
        }
    }
}

Operation¶

The operation type represents the input, output, and possible errors of an API operation. Operation shapes are bound to resource shapes and service shapes. Operation shapes are defined using the operation_statement.

An operation is an object that supports the following key-value pairs:

The following example defines an operation shape that accepts an input structure named Input, returns an output structure named Output, and can potentially return the NotFound or BadRequest error structures.

operation MyOperation {
    input: Input,
    output: Output,
    errors: [NotFound, BadRequest]
}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#MyOperation": {
            "type": "operation",
            "input": {
                "target": "smithy.example#Input"
            },
            "output": {
                "target": "smithy.example#Output"
            },
            "errors": [
                {
                    "target": "smithy.example#NotFound"
                },
                {
                    "target": "smithy.example#BadRequest"
                }
            ]
        }
    }
}

operation MyOperation {
    input: Input
}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#MyOperation": {
            "type": "operation",
            "input": {
                "target": "smithy.example#Input"
            }
        }
    }
}

operation MyOperation {
    output: Output
}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#MyOperation": {
            "type": "operation",
            "output": {
                "target": "smithy.example#Output"
            }
        }
    }
}

operation MyOperation {
    errors: [NotFound, BadRequest]
}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#MyOperation": {
            "type": "operation",
            "errors": [
                {
                    "target": "smithy.example#NotFound"
                },
                {
                    "target": "smithy.example#BadRequest"
                }
            ]
        }
    }
}

Resource¶

Smithy defines a resource as an entity with an identity that has a set of operations.

A resource shape is defined using a resource_statement and supports the following properties:

namespace smithy.example

resource Forecast {
    identifiers: {
        forecastId: ForecastId
    }
}

string ForecastId

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#Forecast": {
            "type": "resource",
            "identifiers": {
                "forecastId": {
                    "target": "smithy.example#ForecastId"
                }
            }
        },
        "smithy.example#ForecastId": {
            "type": "string"
        }
    }
}

resource ResourceA {
    identifiers: {
        a: String
    },
    resources: [ResourceB],
}

resource ResourceB {
    identifiers: {
        a: String,
        b: String,
    },
    resources: [ResourceC],
}

resource ResourceC {
    identifiers: {
        a: String,
        b: String,
        c: String,
    }
}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#ResourceA": {
            "type": "resource",
            "resources": [
                {
                    "target": "smithy.example#ResourceB"
                }
            ],
            "identifiers": {
                "a": {
                    "target": "smithy.api#String"
                }
            }
        },
        "smithy.example#ResourceB": {
            "type": "resource",
            "resources": [
                {
                    "target": "smithy.example#ResourceC"
                }
            ],
            "identifiers": {
                "a": {
                    "target": "smithy.api#String"
                },
                "b": {
                    "target": "smithy.api#String"
                }
            }
        },
        "smithy.example#ResourceC": {
            "type": "resource",
            "identifiers": {
                "a": {
                    "target": "smithy.api#String"
                },
                "b": {
                    "target": "smithy.api#String"
                },
                "c": {
                    "target": "smithy.api#String"
                }
            }
        }
    }
}

resource ResourceA {
    identifiers: {
        a: String,
        b: String,
    },
    resources: [Invalid1, Invalid2],
}

resource Invalid1 {
    // Invalid: missing "a".
    identifiers: {
        b: String,
    },
}

resource Invalid2 {
    identifiers: {
        a: String,
        // Invalid: does not target the same shape.
        b: SomeOtherString,
    },
}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#ResourceA": {
            "type": "resource",
            "identifiers": {
                "a": {
                    "target": "smithy.api#String"
                },
                "b": {
                    "target": "smithy.api#String"
                }
            },
            "resources": [
                {
                    "target": "smithy.example#Invalid1"
                },
                {
                    "target": "smithy.example#Invalid2"
                }
            ]
        },
        "smithy.example#Invalid1": {
            "type": "resource",
            "identifiers": {
                "b": {
                    "target": "smithy.api#String"
                }
            }
        },
        "smithy.example#Invalid2": {
            "type": "resource",
            "identifiers": {
                "a": {
                    "target": "smithy.api#String"
                },
                "b": {
                    "target": "smithy.example#SomeOtherString"
                }
            }
        }
    }
}

resource Forecast {
    identifiers: {
        forecastId: ForecastId,
    },
    read: GetForecast,
}

@readonly
operation GetForecast {
    input: GetForecastInput,
    output: GetForecastOutput
}

structure GetForecastInput {
    @required
    forecastId: ForecastId,
}

structure GetForecastOutput {
    @required
    weather: WeatherData,
}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#Forecast": {
            "type": "resource",
            "identifiers": {
                "forecastId": {
                    "target": "smithy.example#ForecastId"
                }
            },
            "read": {
                "target": "smithy.example#GetForecast"
            }
        },
        "smithy.example#GetForecast": {
            "type": "operation",
            "input": {
                "target": "smithy.example#GetForecastInput"
            },
            "output": {
                "target": "smithy.example#GetForecastOutput"
            },
            "traits": {
                "smithy.api#readonly": true
            }
        },
        "smithy.example#GetForecastInput": {
            "type": "structure",
            "members": {
                "forecastId": {
                    "target": "smithy.example#ForecastId",
                    "traits": {
                        "smithy.api#required": true
                    }
                }
            }
        },
        "smithy.example#GetForecastOutput": {
            "type": "structure",
            "members": {
                "weather": {
                    "target": "smithy.example#WeatherData",
                    "traits": {
                        "smithy.api#required": true
                    }
                }
            }
        }
    }
}

resource Forecast {
    identifiers: {
        forecastId: ForecastId,
    },
    collectionOperations: [BatchPutForecasts],
}

operation BatchPutForecasts {
    input: BatchPutForecastsInput,
    output: BatchPutForecastsOutput
}

structure BatchPutForecastsInput {
    @required
    forecasts: BatchPutForecastList,
}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#Forecast": {
            "type": "resource",
            "identifiers": {
                "forecastId": {
                    "target": "smithy.example#ForecastId"
                }
            },
            "collectionOperations": [
                {
                    "target": "smithy.example#BatchPutForecasts"
                }
            ]
        },
        "smithy.example#BatchPutForecasts": {
            "type": "operation",
            "input": {
                "target": "smithy.example#BatchPutForecastsInput"
            },
            "output": {
                "target": "smithy.example#BatchPutForecastsOutput"
            }
        },
        "smithy.example#BatchPutForecastsInput": {
            "type": "structure",
            "members": {
                "forecasts": {
                    "target": "smithy.example#BatchPutForecastList",
                    "traits": {
                        "smithy.api#required": true
                    }
                }
            }
        }
    }
}

resource Forecast {
    // continued from above
    resources: [HistoricalForecast],
}

resource HistoricalForecast {
    identifiers: {
        forecastId: ForecastId,
        historicalId: HistoricalForecastId,
    },
    read: GetHistoricalForecast,
    list: ListHistoricalForecasts,
}

@readonly
operation GetHistoricalForecast {
    input: GetHistoricalForecastInput,
    output: GetHistoricalForecastOutput
}

structure GetHistoricalForecastInput {
    @required
    @resourceIdentifier("forecastId")
    customForecastIdName: ForecastId,

    @required
    @resourceIdentifier("historicalId")
    customHistoricalIdName: String
}

resource Forecast {
    identifiers: {
        forecastId: ForecastId,
    },
    put: PutForecast,
    create: CreateForecast,
    read: GetForecast,
    update: UpdateForecast,
    delete: DeleteForecast,
    list: ListForecasts,
}

operation PutForecast {
    input: PutForecastInput,
    output: PutForecastOutput
}

@idempotent
structure PutForecastInput {
    // The client provides the resource identifier.
    @required
    forecastId: ForecastId,

    chanceOfRain: Float
}

operation CreateForecast {
    input: CreateForecastInput,
    output: CreateForecastOutput
}

@collection
operation CreateForecast {
    input: CreateForecastInput,
    output: CreateForecastOutput
}

structure CreateForecastInput {
    // No identifier is provided by the client, so the service is
    // responsible for providing the identifier of the resource.
    chanceOfRain: Float,
}

@readonly
operation GetForecast {
    input: GetForecastInput,
    output: GetForecastOutput,
    errors: [ResourceNotFound]
}

structure GetForecastInput {
    @required
    forecastId: ForecastId,
}

operation UpdateForecast {
    input: UpdateForecastInput,
    output: UpdateForecastOutput,
    errors: [ResourceNotFound]
}

structure UpdateForecastInput {
    @required
    forecastId: ForecastId,

    chanceOfRain: Float,
}

@idempotent
operation DeleteForecast {
    input: DeleteForecastInput,
    output: DeleteForecastOutput,
    errors: [ResourceNotFound]
}

structure DeleteForecastInput {
    @required
    forecastId: ForecastId,
}

@collection @readonly @paginated
operation ListForecasts {
    input: ListForecastsInput,
    output: ListForecastsOutput
}

structure ListForecastsInput {
    maxResults: Integer,
    nextToken: String
}

structure ListForecastsOutput {
    nextToken: String,
    @required
    forecasts: ForecastList
}

list ForecastList {
    member: ForecastId
}

@references([{resource: HistoricalForecast}])
structure HistoricalReference {
    forecastId: ForecastId,
    historicalId: HistoricalForecastId
}

@references([{resource: HistoricalForecast,
              ids: {
                  forecastId: "customForecastId",
                  historicalId: "customHistoricalId"
              }])
structure AnotherHistoricalReference {
    customForecastId: String,
    customHistoricalId: String,
}

resource SimpleResource {
    identifiers: {
        foo: String,
    }
}

@references([{resource: SimpleResource}])
string SimpleResourceReference

Structure, map, and union trait values¶

Traits that are a structure, union, or map are defined using a JSON-like object in the Smithy IDL or a JSON object in the JSON AST. The wrapping braces ({}) for the object MUST be omitted in the Smithy IDL. For example:

@structuredTrait(foo: "bar", baz: "bam")

Nested structure, map, and union values are defined like JSON value using the node value productions:

@structuredTrait(
    foo: {
        bar: "baz",
        qux: "true",
    }
)

Omitting a value is allowed on list, set, map, and structure traits if the shapes have no length constraints or required members.

Annotation traits¶

A structure trait with no members is called an annotation trait. The following example defines an annotation trait named foo:

namespace smithy.example

@trait
structure foo {}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#foo": {
            "type": "structure",
            "traits": {
                "smithy.api#trait": true
            }
        }
    }
}

It's hard to predict what information a trait needs to capture when modeling a domain; a trait might start out as a simple annotation, but later might need additional information. Smithy explicitly supports this use case by allowing null and true to be provided for traits that have a structure value.

The following applications of the foo annotation trait are all equivalent:

namespace smithy.example

@foo
string MyString1

@foo()
string MyString2

@foo(true)
string MyString3

@foo(null)
string MyString4

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#MyString1": {
            "type": "string",
            "traits": {
                "smithy.api#foo": null
            }
        },
        "smithy.example#MyString2": {
            "type": "string",
            "traits": {
                "smithy.api#foo": {}
            }
        },
        "smithy.example#MyString3": {
            "type": "string",
            "traits": {
                "smithy.api#foo": true
            }
        },
        "smithy.example#MyString4": {
            "type": "string",
            "traits": {
                "smithy.api#foo": null
            }
        }
    }
}

A member can be safely added to an annotation trait structure if the member is not marked as required. The applications of the foo trait in the previous example and the following example are all valid even after adding a member to the foo trait:

namespace smithy.example

@trait
structure foo {
    baz: String,
}

@foo(baz: "bar")
string MyString5

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#foo": {
            "type": "structure",
            "members": {
                "baz": {
                    "target": "smithy.api#String"
                }
            },
            "traits": {
                "smithy.api#trait": true
            }
        },
        "smithy.example#MyString5": {
            "type": "string",
            "traits": {
                "smithy.api#foo": {
                    "baz": "bar"
                }
            }
        }
    }
}

Other trait values¶

All other trait values MUST adhere to the JSON type mappings defined in Trait JSON values table.

Trait definition properties¶

The trait definition trait is a structure that supports the following members:

The following example defines two custom traits: beta and structuredTrait:

namespace smithy.example

/// A trait that can be applied to a member.
@trait(selector: "member:of(structure)")
structure beta {}

/// A trait that has members.
@trait(selector: "string", conflicts: [beta])
structure structuredTrait {
    @required
    lorem: StringShape,

    @required
    ipsum: StringShape,

    dolor: StringShape,
}

// Apply the "beta" trait to the "foo" member.
structure MyShape {
    @required
    @beta
    foo: StringShape,
}

// Apply the structuredTrait to the string.
@structuredTrait(
    lorem: "This is a custom trait!",
    ipsum: "lorem and ipsum are both required values.")
string StringShape

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#beta": {
            "type": "apply",
            "traits": {
                "smithy.api#type": "structure",
                "smithy.api#trait": {
                    "selector": "member:of(structure)"
                },
                "smithy.api#documentation": "A trait that can be applied to a member."
            }
        },
        "smithy.example#structuredTrait": {
            "type": "apply",
            "traits": {
                "smithy.api#type": "structure",
                "smithy.api#trait": {
                    "selector": "string",
                    "conflicts": [
                        "smithy.example#beta"
                    ]
                },
                "smithy.api#members": {
                    "lorem": {
                        "target": "StringShape",
                        "required": true
                    },
                    "dolor": {
                        "target": "StringShape"
                    }
                },
                "smithy.api#documentation": "A trait that has members."
            }
        },
        "smithy.example#MyShape": {
            "type": "apply",
            "traits": {
                "smithy.api#type": "structure",
                "smithy.api#members": {
                    "beta": {
                        "target": "StringShape",
                        "required": true,
                        "beta": true
                    }
                }
            }
        },
        "smithy.example#StringShape": {
            "type": "apply",
            "traits": {
                "smithy.api#type": "string",
                "smithy.api#structuredTrait": {
                    "lorem": "This is a custom trait!",
                    "ipsum": "lorem and ipsum are both required values."
                }
            }
        }
    }
}

Trait JSON values¶

The value provided for a trait MUST be compatible with the shape defined for the trait. The following table defines each shape type that is available to target from trait definitions and how values for those shapes are defined in JSON.

Trait values MUST be compatible with any constraint traits found related to the shape being validated.

box trait¶

Summary

Indicates that a shape is boxed. When a member is marked with this trait or the shape targeted by a member is marked with this trait, the member may or may not contain a value, and the member has no default value.

Boolean, byte, short, integer, long, float, and double shapes are only considered boxed if they are marked with the box trait. All other shapes are always considered boxed.

Trait selector

:test(boolean, byte, short, integer, long, float, double,
      member > :test(boolean, byte, short, integer, long, float, double))

A boolean, byte, short, integer, long, float, double shape or a member that targets one of these shapes

Value type

Annotation trait.

The box trait is primarily used to influence code generation. For example, in Java, this might mean the value provided as the member of an aggregate shape can be set to null. In a language like Rust, this might mean the value is wrapped in an Option type.

@box
integer BoxedInteger

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#BoxedInteger": {
            "type": "integer",
            "traits": {
                "smithy.api#box": true
            }
        }
    }
}

The prelude contains predefined simple shapes that can be used in all Smithy models, including boxed and unboxed shapes.

deprecated trait¶

Summary

Marks a shape or member as deprecated.

Trait selector

*

Value type

structure

The deprecated trait is a structure that supports the following members:

@deprecated
string SomeString

@deprecated(message: "This shape is no longer used.", since: "1.3")
string OtherString

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#SomeString": {
            "type": "string",
            "traits": {
                "smithy.api#deprecated": {}
            }
        },
        "smithy.example#OtherString": {
            "type": "string",
            "traits": {
                "smithy.api#deprecated": {
                    "message": "This shape is no longer used.",
                    "since": "1.3"
                }
            }
        }
    }
}

error trait¶

Summary

Indicates that a structure shape represents an error. All shapes referenced by the errors list of an operation MUST be targeted with this trait.

Trait selector

structure

Value type

string that MUST be set to "client" or "server" to indicate if the client or server is at fault for the error.

Conflicts with

trait definition

The following structure defines a throttling error.

@error("client")
structure ThrottlingError {}

Note that this structure is lacking the retryable trait that generically lets clients know that the error is retryable.

@error("client")
@retryable
structure ThrottlingError {}

When using an HTTP-based protocol, it is recommended to add an httpError trait to use an appropriate HTTP status code with the error.

@error("client")
@retryable
@httpError(429)
structure ThrottlingError {}

The message member of an error structure is special-cased. It contains the human-readable message that describes the error. If the message member is not defined in the structure, code generated for the error may not provide an idiomatic way to access the error message (e.g., an exception message in Java).

@error("client")
@retryable
@httpError(429)
structure ThrottlingError {
    @required
    message: String,
}

enum trait¶

Summary

Constrains the acceptable values of a string to a fixed set.

Trait selector

string

Value type

map of enum constant values to structures optionally containing a name, documentation, tags, and/or a deprecation flag.

Smithy models SHOULD apply the enum trait when string shapes have a fixed set of allowable values.

The enum trait is a map of allowed string values to enum constant definition structures. Enum values do not allow aliasing; all enum constant values MUST be unique across the entire set.

An enum definition is a structure that supports the following optional members:

The following example defines an enum of valid string values for MyString.

@enum(
    t2.nano: {
        name: "T2_NANO",
        documentation: """
            T2 instances are Burstable Performance
            Instances that provide a baseline level of CPU
            performance with the ability to burst above the
            baseline.""",
        tags: ["ebsOnly"]
    },
    t2.micro: {
        name: "T2_MICRO",
        documentation: """
            T2 instances are Burstable Performance
            Instances that provide a baseline level of CPU
            performance with the ability to burst above the
            baseline.""",
        tags: ["ebsOnly"]
    },
    m256.mega: {
        name: "M256_MEGA",
        deprecated: true
    }
)
string MyString

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#MyString": {
            "type": "string",
            "traits": {
                "smithy.api#enum": {
                    "t2.nano": {
                        "name": "T2_NANO",
                        "documentation": "T2 instances are ...",
                        "tags": [
                            "ebsOnly"
                        ]
                    },
                    "t2.micro": {
                        "name": "T2_MICRO",
                        "documentation": "T2 instances are ...",
                        "tags": [
                            "ebsOnly"
                        ]
                    },
                    "m256.mega": {
                        "name": "M256_MEGA",
                        "deprecated": true
                    }
                }
            }
        }
    }
}

idRef trait¶

Summary

Indicates that a string value MUST contain a valid absolute shape ID.

The idRef trait is used primarily when declaring trait definitions in a model. A trait definition that targets a string shape with the idRef trait indicates that when the defined trait is applied to a shape, the value of the trait MUST be a valid shape ID. The idRef trait can also be applied at any level of nesting on shapes referenced by trait definitions.

Trait selector

:test(string, member > string)

A string shape or a member that targets a string shape

Value type

structure

The idRef trait is a structure that supports the following optional members:

To illustrate an example, a custom trait named integerRef is defined. This trait can be attached to any shape, and the value of the trait MUST contain a valid shape ID that targets an integer shape in the model.

namespace smithy.example

@trait
@idRef(failWhenMissing: true, selector: "integer")
string IntegerRefTraitValue

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#integerRef": {
            "type": "string",
            "traits": {
                "smithy.api#trait": true,
                "smithy.api#idRef": {
                    "failWhenMissing": true,
                    "selector": "integer"
                }
            }
        }
    }
}

Given the following model,

namespace smithy.example

@integerRef(NotFound)
string InvalidShape1

@integerRef(String)
string InvalidShape2

@integerRef("invalid-shape-id!")
string InvalidShape3

@integerRef(Integer)
string ValidShape

@integerRef(MyShape)
string ValidShape2

string MyShape

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#InvalidShape1": {
            "type": "string",
            "traits": {
                "smithy.api#integerRef": "NotFound"
            }
        },
        "smithy.example#InvalidShape2": {
            "type": "string",
            "traits": {
                "smithy.api#integerRef": "String"
            }
        },
        "smithy.example#InvalidShape3": {
            "type": "string",
            "traits": {
                "smithy.api#integerRef": "invalid-shape-id!"
            }
        },
        "smithy.example#ValidShape": {
            "type": "string",
            "traits": {
                "smithy.api#integerRef": "Integer"
            }
        },
        "smithy.example#ValidShape2": {
            "type": "string",
            "traits": {
                "smithy.api#integerRef": "MyShape"
            }
        },
        "smithy.example#MyShape": {
            "type": "string"
        }
    }
}

• InvalidShape1 is invalid because the "NotFound" shape cannot be found in the model.
• InvalidShape2 is invalid because "smithy.api#String" targets a string which does not match the "integer" selector.
• InvalidShape3 is invalid because "invalid-shape-id!" is not a syntactically correct absolute shape ID.
• ValidShape is valid because "smithy.api#Integer" targets an integer.
• ValidShape2 is valid because "MyShape" is a relative ID that targets smithy.example#MyShape.

length trait¶

Summary

Constrains a shape to minimum and maximum number of elements or size.

Trait selector

:test(list, map, string, blob, member > :each(list, map, string, blob))

Any list, map, string, or blob; or a member that targets one of these shapes

Value type

structure

The length trait is a structure that contains the following members:

At least one of min, max is required.

The following table describes what a length trait constrains when applied to the corresponding shape:

@length(min: 1, max: 10)
string MyString

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#MyString": {
            "type": "string",
            "traits": {
                "smithy.api#length": {
                    "min": 1,
                    "max": 10
                }
            }
        }
    }
}

pattern trait¶

Summary

Restricts string shape values to a specified regular expression.

Trait selector

:test(string, member > string)

A string or a member that targets a string

Value type

string

Smithy regular expressions MUST be valid regular expressions according to the ECMA 262 regular expression dialect. Patterns SHOULD avoid the use of conditionals, directives, recursion, lookahead, look-behind, back-references, and look-around in order to ensure maximum compatibility across programming languages.

@pattern("\\w+")
string MyString

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#MyString": {
            "type": "string",
            "traits": {
                "smithy.api#pattern": "\\w+"
            }
        }
    }
}

private trait¶

Summary

Prevents models defined in a different namespace from referencing the targeted shape.

Trait selector

*

Value type

Annotation trait

Shapes marked as private cannot be accessed outside of the namespace in which the shape is defined. The private trait is meant only to control access from within the model itself and SHOULD NOT influence code-generation of the targeted shape.

range trait¶

Summary

Restricts allowed values of byte, short, integer, long, float, double, bigDecimal, and bigInteger shapes within an acceptable lower and upper bound.

Trait selector

:test(number, member > number)

A number or a member that targets a number

Value type

structure

The length trait is a structure that contains the following members:

At least one of min or max is required. min and max accept both integers and real numbers. Real numbers may only be applied to float, double, or bigDecimal shapes. min and max MUST fall within the allowable range of the targeted numeric shape to which it is applied.

@range(min: 1, max: 10)
integer MyInt

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#MyInt": {
            "type": "integer",
            "traits": {
                "smithy.api#range": {
                    "min": 1,
                    "max": 10
                }
            }
        }
    }
}

required trait¶

Summary

Marks a structure member as required, meaning a value for the member MUST be present.

Trait selector

member:of(structure)

Member of a structure

Value type

Annotation trait.

The required trait applies to structure data, operation input, output, and errors. When a member that is part of the input of an operation is marked as required, a client MUST provide a value for the member when calling the operation. When a member that is part of the output of an operation or an error is marked as required, a service MUST provide a value for the member in a response.

structure MyStructure {
    @required
    foo: FooString,
}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#MyStructure": {
            "type": "structure",
            "members": {
                "foo": {
                    "target": "smithy.example#FooString",
                    "traits": {
                        "smithy.api#required": true
                    }
                }
            }
        }
    }
}

uniqueItems trait¶

Summary

Indicates that the items in a list MUST be unique.

Trait selector

:test(list > member > simpleType)

A list that targets any simple type.

Value type

Annotation trait.

@uniqueItems
list MyList {
    member: String,
}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#MyList": {
            "type": "list",
            "member": {
                "target": "smithy.api#String"
            },
            "traits": {
                "smithy.api#uniqueItems": true
            }
        }
    }
}

idempotencyToken trait¶

Summary

Defines the input member of an operation that is used by the server to identify and discard replayed requests.

Trait selector

:test(member:of(structure) > string)

Any structure member that targets a string

Value type

Annotation trait

Only a single member of the input of an operation can be targeted by the idempotencyToken trait; only top-level structure members of the input of an operation are considered.

A unique identifier (typically a UUID) SHOULD be used by the client when providing the value for the request token member. When the request token is present, the service MUST ensure that the request is not replayed within a service-defined period of time. This allows the client to safely retry operation invocations, including operations that are not read-only, that fail due to networking issues or internal server errors. The service uses the provided request token to identify and discard duplicate requests.

Client implementations MAY automatically provide a value for a request token member if and only if the member is not explicitly provided.

operation AllocateWidget {
    input: AllocateWidgetInput
}

structure AllocateWidgetInput {
    @idempotencyToken
    clientToken: String,
}

idempotent trait¶

Summary

Indicates that the intended effect on the server of multiple identical requests with an operation is the same as the effect for a single such request.

Trait selector

operation

Value type

Annotation trait

Conflicts with

readonly trait

@idempotent
operation GetSomething {
    input: DeleteSomething,
    output: DeleteSomethingOutput
}

readonly trait¶

Summary

Indicates that an operation is effectively read-only.

Trait selector

operation

Value type

Annotation trait

Conflicts with

idempotent trait

@readonly
operation GetSomething {
    input: GetSomethingInput,
    output: GetSomethingOutput
}

retryable trait¶

Summary

Indicates that an error MAY be retried by the client.

Trait selector

structure[trait|error]

A structure shape with the error trait

Value type

structure

The retryable trait is a structure that contains the following members:

@error("server")
@retryable
@httpError(503)
structure ServiceUnavailableError {}

@error("client")
@retryable(throttling: true)
@httpError(429)
structure ThrottlingError {}

paginated trait¶

Summary

The paginated trait indicates that an operation intentionally limits the number of results returned in a single response and that multiple invocations might be necessary to retrieve all results.

Trait selector

:test(operation, service)

An operation or service

Value type

structure

Pagination is the process of dividing large result sets into discrete pages. Smithy provides a built-in pagination mechanism that utilizes a cursor.

The paginated trait is a structure that contains the following members:

The following example defines a paginated operation that sets each value explicitly on the operation.

namespace smithy.example

@collection @readonly
@paginated(inputToken: "nextToken", outputToken: "nextToken",
           pageSize: "maxResults", items: "foos")
operation GetFoos {
    input: GetFoosInput,
    output: GetFoosOutput
}

structure GetFoosInput {
    maxResults: Integer,
    nextToken: String
}

structure GetFoosOutput {
    nextToken: String,

    @required
    foos: StringList,
}

list StringList {
    member: String
}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#GetFoos": {
            "type": "operation",
            "input": {
                "target": "smithy.example#GetFoosInput"
            },
            "output": {
                "target": "smithy.example#GetFoosOutput"
            },
            "traits": {
                "smithy.api#readonly": true,
                "smithy.api#collection": true,
                "smithy.api#paginated": {
                    "inputToken": "nextToken",
                    "outputToken": "nextToken",
                    "pageSize": "maxResults",
                    "items": "foos"
                }
            }
        },
        "smithy.example#GetFoosInput": {
            "type": "structure",
            "members": {
                "maxResults": {
                    "target": "smithy.api#Integer"
                },
                "nextToken": {
                    "target": "smithy.api#String"
                }
            }
        },
        "smithy.example#GetFoosOutput": {
            "type": "structure",
            "members": {
                "nextToken": {
                    "target": "smithy.api#String"
                },
                "foos": {
                    "target": "smithy.example#StringList",
                    "traits": {
                        "smithy.api#required": true
                    }
                }
            }
        },
        "smithy.example#StringList": {
            "type": "list",
            "member": {
                "target": "smithy.api#String"
            }
        }
    }
}

Attaching the paginated trait to a service provides default pagination configuration settings to all operations bound within the closure of the service. Pagination settings configured on an operation override any inherited service setting.

The following example defines a paginated operation that inherits some settings from a service.

namespace smithy.example

@paginated(inputToken: "nextToken", outputToken: "nextToken",
           pageSize: "maxResults")
service Example {
    version: "2019-06-27",
    operations: [GetFoos],
}

@collection @readonly @paginated(items: "foos")
operation GetFoos {
    input: GetFoosInput,
    output: GetFoosOutput
}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#Example": {
            "type": "service",
            "version": "2019-06-27",
            "traits": {
                "smithy.api#paginated": {
                    "inputToken": "nextToken",
                    "outputToken": "nextToken",
                    "pageSize": "maxResults"
                }
            }
        },
        "smithy.example#GetFoos": {
            "type": "operation",
            "input": {
                "target": "smithy.example#GetFoosInput"
            },
            "output": {
                "target": "smithy.example#GetFoosOutput"
            },
            "traits": {
                "smithy.api#readonly": true,
                "smithy.api#collection": true,
                "smithy.api#paginated": {
                    "items": "foos"
                }
            }
        }
    }
}

The values for outputToken and items are paths. Paths are a series of identifiers separated by dots (.) where each identifier represents a member name in a structure. The first member name MUST correspond to a member of the output structure and each subsequent member name MUST correspond to a member in the previously referenced structure. Paths MUST adhere to the following ABNF.

path =
    identifier *("." identifier)

The following example defines a paginated operation which uses a result wrapper where the output token and items are referenced by paths.

namespace smithy.example

@readonly
@paginated(inputToken: "nextToken", outputToken: "result.nextToken",
           pageSize: "maxResults", items: "result.foos")
operation GetFoos {
    input: GetFoosInput,
    output: GetFoosOutput
}

structure GetFoosInput {
    maxResults: Integer,
    nextToken: String
}

structure GetFoosOutput {
    @required
    result: ResultWrapper
}

structure ResultWrapper {
    nextToken: String,

    @required
    foos: StringList,
}

list StringList {
    member: String
}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#GetFoos": {
            "type": "operation",
            "input": {
                "target": "smithy.example#GetFoosInput"
            },
            "output": {
                "target": "smithy.example#GetFoosOutput"
            },
            "traits": {
                "smithy.api#readonly": true,
                "smithy.api#paginated": {
                    "inputToken": "nextToken",
                    "outputToken": "result.nextToken",
                    "pageSize": "maxResults",
                    "items": "result.foos"
                }
            }
        },
        "smithy.example#GetFoosInput": {
            "type": "structure",
            "members": {
                "maxResults": {
                    "target": "smithy.api#Integer"
                },
                "nextToken": {
                    "target": "smithy.api#String"
                }
            }
        },
        "smithy.example#GetFoosOutput": {
            "type": "structure",
            "members": {
                "result": {
                    "target": "smithy.example#ResultWrapper",
                    "traits": {
                        "smithy.api#required": true
                    }
                }
            }
        },
        "smithy.example#ResultWrapper": {
            "type": "structure",
            "members": {
                "nextToken": {
                    "target": "smithy.api#String"
                },
                "foos": {
                    "target": "smithy.example#StringList",
                    "traits": {
                        "smithy.api#required": true
                    }
                }
            }
        },
        "smithy.example#StringList": {
            "type": "list",
            "member": {
                "target": "smithy.api#String"
            }
        }
    }
}

references trait¶

Summary

Defines the Resource shapes that are referenced by a string shape or a structure shape and the members of the structure that provide values for the identifiers of the resource.

References provide the ability for tooling to dereference a resource reference at runtime. For example, if a client receives a response from a service that contains references, the client could provide functionality to resolve references by name, allowing the end-user to invoke operations on a specific referenced resource.

Trait selector

:test(structure, string)

Any structure or string

Value type

list of Reference structures

The references trait is a list of Reference structures that contain the following members:

References MAY NOT be resolvable at runtime in the following circumstances:

1. The members that make up the ids are not present in a structure at runtime (e.g., a member is not marked as required trait)
2. The targeted resource and/or service shape is not part of the model
3. The reference is bound to a specific service that is unknown to the tool

The following example defines several references:

@references([
    {resource: Forecast},
    {resource: ShapeName},
    {resource: Meteorologist},
    {
        resource: com.foo.baz#Object,
        service: com.foo.baz#Service,
        ids: {bucket: "bucketName", object: "objectKey"},
    ])
structure ForecastInformation {
    someId: SomeShapeIdentifier,

    @required
    forecastId: ForecastId,

    @required
    meteorologistId: MeteorologistId,

    @required
    otherData: SomeOtherShape,

    @required
    bucketName: BucketName,

    @required
    objectKey: ObjectKey,
}

resourceIdentifier trait¶

Summary

Indicates that the targeted structure member provides an identifier for a resource.

Trait selector

:test(member:of(structure)[trait|required] > string)

Any required member of a structure that targets a string

Value type

string

The resourceIdentifier trait may only be used on members of structures that serve as input shapes for operations bound to resources. The string value provided must correspond to the name of an identifier for said resource. The trait is not required when the name of the input structure member is an exact match for the name of the resource identifier.

resource File {
    identifiers: {
        directory: "String",
        fileName: "String",
    },
    read: GetFile,
}

@readonly
operation GetFile {
    input: GetFileInput,
    output: GetFileOutput,
    errors: [NoSuchResource]
}

structure GetFileInput {
    @required
    directory: String,

    // resourceIdentifier is used because the input member name
    // does not match the resource identifier name
    @resourceIdentifier("fileName")
    @required
    name: String,
}

protocols trait¶

Summary

Defines the protocols supported by a service.

Trait selector

service

Value type

list of protocol structure

Smithy is protocol agnostic, which means it focuses on the interfaces and abstractions that are provided to end-users rather than how the data is sent over the wire. In Smithy, a protocol is a named set of rules that defines the syntax and semantics of how a client and server communicate. A protocol name defines both the application protocol of a service and the serialization formats used in messages. These serialization formats MAY be influenced by payload serialization traits like jsonName trait and xmlAttribute trait.

The protocols trait of a service defines a priority ordered list of protocols supported by the service and the authentication schemes that each protocol supports. A client MUST understand at least one of the protocols in order to successfully communicate with the service.

The value of the protocols trait is a list of protocol structures. Each protocol structure supports the following members:

The following example defines a service that supports both the "smithy.example" protocol and the "aws.mqtt" protocols. The "aws.mqtt" protocol is defined with an optional list of tags.

@protocols([
    {name: "smithy.example", auth: ["http-basic"]},
    {name: "aws.mqtt", auth: ["x.509"], tags: ["internal"]}])
service WeatherService {
    version: "2017-02-11",
}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#WeatherService": {
            "type": "service",
            "version": "2017-02-11",
            "traits": {
                "smithy.api#protocols": [
                    {
                        "name": "smithy.example",
                        "auth": [
                            "http-basic"
                        ]
                    },
                    {
                        "name": "aws.mqtt",
                        "auth": [
                            "x.509"
                        ],
                        "tags": [
                            "internal"
                        ]
                    }
                ]
            }
        }
    }
}

An operation bound to a service is expected to support every listed auth scheme of every protocol unless the operation or the service is annotated with the auth trait.

auth trait¶

Summary

Defines the priority ordered authentication schemes supported by a service or operation. When applied to a service, it defines the default authentication schemes of every operation in the service. When applied to an operation, it defines the list of all authentication schemes supported by the operation, overriding any auth trait specified on a service.

Trait selector

:test(service, operation)

Service or operation shapes

Value type

list<string> which represents a priority ordered list of values that reference authentication schemes defined on a service shape.

The auth trait is used to explicitly define which authentication schemes defined by the protocols trait of a service are supported by an operation.

Operations that are not annotated with the auth trait inherit the auth trait of the service they are bound to, and if the service is not annotated with the auth trait, then the operation is expected to support each of the authentication schemes defined by all of the protocols of the service. Each entry in the auth trait MUST map to a corresponding auth property in the protocols trait of a service with the exception of the "none" auth scheme which can be used without defining it in a protocol.

When connecting to a service using a specific protocol, only the intersection of the auth schemes listed in the selected protocol and the auth schemes defined in the resolved auth trait are eligible for the client to use.

The following example defines two operations:

• OperationA defines an explicit list of the authentication schemes it supports using the auth trait.
• OperationB does is not annotated with the auth trait, so the schemes supported by this operation inherit from the protocols trait defined on the service.

@protocols([{name: "smithy.example", auth: ["http-basic", "http-digest"]}])
// Every operation by default should support http-basic and http-digest.
@auth(["http-basic", "http-digest"])
service AuthenticatedService {
    version: "2017-02-11",
    operations: [OperationA, OperationB]
}

// This operation is configured to either be unauthenticated
// or to use http-basic. It is not expected to support http-digest.
@auth(["none", "http-basic"])
operation OperationA {}

// This operation defines no auth, so it is expected to support the auth
// defined on the service: http-basic and http-digest.
operation OperationB {}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#AuthenticatedService": {
            "type": "service",
            "version": "2017-02-11",
            "operations": [
                {
                    "target": "smithy.example#OperationA"
                },
                {
                    "target": "smithy.example#OperationB"
                }
            ],
            "traits": {
                "smithy.api#protocols": [
                    {
                        "name": "smithy.example",
                        "auth": [
                            "http-basic",
                            "http-digest"
                        ]
                    }
                ]
            }
        },
        "smithy.example#OperationA": {
            "type": "operation",
            "traits": {
                "smithy.api#auth": [
                    "none",
                    "http-basic"
                ]
            }
        },
        "smithy.example#OperationB": {
            "type": "operation"
        }
    }
}

The following auth trait is invalid because it uses an auth trait scheme that is not supported by any of the protocols of the service:

@protocols([{name: "smithy.example", auth: ["http-basic"]}])
@auth(["http-digest"]) // <-- Invalid!
service InvalidExample {
    version: "2017-02-11"
}

The following example demonstrates how a service that supports multiple protocols can define different authentication schemes for each protocol.

@protocols([
    {name: "example.foo", auth: ["http-basic", "http-digest"]},
    {name: "example.baz", auth: ["x.509"]}])
@auth(["http-basic", "x.509"])
service AuthenticatedService {
    version: "2017-02-11",
    operations: [OperationA, OperationB]
}

@auth(["http-digest", "x.509"])
operation OperationA {}

operation OperationB {}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#AuthenticatedService": {
            "type": "service",
            "version": "2017-02-11",
            "operations": [
                {
                    "target": "smithy.example#OperationA"
                },
                {
                    "target": "smithy.example#OperationB"
                }
            ],
            "traits": {
                "smithy.api#protocols": [
                    {
                        "name": "example.foo",
                        "auth": [
                            "http-basic",
                            "http-digest"
                        ]
                    },
                    {
                        "name": "example.baz",
                        "auth": [
                            "x.509"
                        ]
                    }
                ]
            }
        },
        "smithy.example#OperationA": {
            "type": "operation",
            "traits": {
                "smithy.api#auth": [
                    "http-digest",
                    "x.509"
                ]
            }
        },
        "smithy.example#OperationB": {
            "type": "operation"
        }
    }
}