10. Resource traits

10.1. nestedProperties trait

Summary

Allows the binding of resource properties to occur within a nested structure deeper than the lifecycle operation's input or output shape.

Trait selector

operation -[input, output]-> structure > member :test(> structure)

A member of a top-level input or output structure member

Value type

Annotation trait.

By default, resource properties are resolved by looking at top-level input and output members. The @nestedProperties trait is used when the properties of a resource are nested one level deeper than top-level input and output members.

resource Forecast {
    properties: { chanceOfRain: Float }
    read: GetForecast
}

@readonly
operation GetForecast {
   output: GetForecastOutput
}

structure GetForecastOutput {
    @nestedProperties
    forecastData: ForecastData
}

structure ForecastData for Forecast {
    $chanceOfRain
}

See also

Member target elision syntax is used to define structure members for a resource property, identifier, or mixin member that do not repeat the target definition.

The shape targeted by the member marked with this trait will have its members used for resource property bindings. These members may not use property trait, or notProperty trait, and Smithy will not perform any resource property binding exclusion or bindings with mismatched property names.

10.2. notProperty trait

Summary

Indicates that a top-level input or output shape member is not bound to a resource property. This trait can also mark another trait as a carrier for @notProperty so that if that trait is applied to a member, the member is considered implicitly marked with @notProperty.

Trait selector

:is(operation -[input, output]-> structure > member, [trait|trait])

A top-level member of an operation's input or output shape, or a trait

Value type

Annotation trait.

By default, top-level input and output members of lifecycle operations must be bound to a resource property or identifier. Members that are neither must have this trait applied, or be annotated with a different trait that has this trait applied.

Use this trait on a resource operation input or output member that explicitly has a purpose unrelated to reading or writing resource properties. Also use this trait on a custom defined Smithy trait used to annotate input or output members for purposes unrelated to resource property modeling such as an idempotency token.

resource Forecast {
    properties: { chanceOfRain: Float }
    update: UpdateForecast
}

operation UpdateForecast {
   input: UpdateForecastInput
}

structure UpdateForecastInput for Forecast {
    $chanceOfRain

    @notProperty
    dryRun: Boolean

    @idempotencyToken
    clientToken: String
}

10.3. noReplace trait

Summary

Indicates that the put lifecycle operation of a resource can only be used to create a resource and cannot replace an existing resource.

Trait selector

resource:test(-[put]->)

A resource with a put lifecycle operation

Value type

Annotation trait.

By default, put lifecycle operations are assumed to both create and replace an existing resource. Some APIs, however, do not support this behavior and require that a resource is first deleted before it can be replaced.

For example, this is the behavior of Amazon DynamoDB's CreateTable operation. The "Table" resource identifier, "TableName", is provided by the client, making it appropriate to model in Smithy as a put lifecycle operation. However, UpdateTable is used to update a table and attempting to call CreateTable on a table that already exists will return an error.

@noReplace
resource Table {
    put: CreateTable
}

@idempotent
operation CreateTable {
    // ...
}

10.4. property trait

Summary

Binds a top-level input or output structure member to a resource property with a different name.

Trait selector

structure > member

A top-level member of an operation's input or output shape

Value type

An object with the following properties:

Property	Type	Description
name	string	Required Name of the resource property to bind the member to.

By default, top-level input or output shape members are bound to the resource property with the same name. In situations where this isn't possible, this trait can be used to specify which property the member is bound to.

Note

This trait should only be used for existing service APIs that need to maintain backwards compatibility with input and output structures, while enabling Smithy's resource property modeling and validation.

resource Forecast {
    properties: { chanceOfRain: Float }
    read: GetForecast
}

@readonly
operation GetForecast {
   output: GetForecastOutput
}

structure GetForecastOutput {
    @property(name: "chanceOfRain")
    howLikelyToRain: Float
}

10.5. references trait

Summary

Defines a design-time reference to Resource shapes. Resource references allow tooling to understand the relationships between resources and how to dereference the location of a resource.

Trait selector

:is(structure, string)

Any structure or string

Value type

list of Reference structures

10.5.1. Reference structure

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

Property	Type	Description
service	Shape ID	The absolute shape ID of the service to which the resource is bound. As with the resource property, the provided shape ID is not required to be resolvable at build time.
resource	Shape ID	Required. The absolute shape ID of the referenced resource. The provided shape ID is not required to be part of the model; references may refer to resources in other models without directly depending on the external package in which the resource is defined. The reference will not be resolvable at build time but MAY be resolvable at runtime if the tool has loaded more than one model.
ids	map<string, string>	Defines a mapping of each resource identifier name to a structure member name that provides its value. Each key in the map MUST refer to one of the identifier names in the identifiers property of the resource, and each value in the map MUST refer to a valid structure member name that targets a string shape. This property MUST be omitted if the references trait is applied to a string shape. This property MAY be omitted if the identifiers of the resource can be mapped implicitly.
rel	string	Defines the semantics of the relationship. The rel property SHOULD contain a link relation as defined in RFC 5988#section-4 (i.e., this value SHOULD contain either a standard link relation or URI).

10.5.2. Runtime resolution of references

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

10.5.3. Implicit identifier mappings example

The following example creates a reference to a HistoricalForecast resource (a resource that requires the "forecastId" and "historicalId" identifiers):

$version: "2"
namespace smithy.example

resource HistoricalForecast {
    identifiers: {
        forecastId: ForecastId
        historicalId: HistoricalForecastId
    }
}

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

Notice that in the above example, the identifiers of the resource were not explicitly mapped to structure members. This is because the targeted structure contains members with names that match the names of the identifiers of the HistoricalForecast resource.

10.5.4. Explicit identifier mappings example

Explicit mappings between identifier names and structure member names can be defined if needed. For example:

$version: "2"
namespace smithy.example

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

10.5.5. Additional examples

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
}

10.5.6. References on string shapes

A reference can be formed on a string shape for resources that have one identifier. References applied to a string shape MUST omit the "ids" property in the reference.

resource SimpleResource {
    identifiers: {
        foo: String
    }
}

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

10.5.7. Implicit ids

The "ids" property of a reference MAY be omitted in any of the following conditions:

1. The shape that the references trait is applied to is a string shape.
2. The shape that the references trait is applied to is a structure shape and all of the identifier names of the resource have corresponding member names that target string shapes.

10.6. resourceIdentifier trait

Summary

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

Trait selector

structure > :test(member[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 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 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]
}

@input
structure GetFileInput for File {
    @required
    $directory

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