8. Documentation traits#

Documentation traits describe shapes in the model in a way that does not materially affect the semantics of the model.

8.1. 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:

Property Type Description
message string Provides a plain text message for a deprecated shape or member.
since string Provides a plain text date or version for when a shape or member was deprecated. 
@deprecated
string SomeString

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

8.2. documentation trait#

Summary
Adds documentation to a shape or member using the CommonMark format.
Trait selector
*
Value type
string
@documentation("This *is* documentation about the shape.")
string MyString

8.2.1. Effective documentation#

The effective documentation trait of a shape is resolved using the following process:

  1. Use the documentation trait of the shape, if present.
  2. If the shape is a Member shapes, then use the documentation trait of the shape targeted by the member, if present.

For example, given the following model,

structure Foo {
    @documentation("Member documentation")
    baz: Baz

    bar: Baz

    qux: String
}

@documentation("Shape documentation")
string Baz

the effective documentation of Foo$baz resolves to "Member documentation", Foo$bar resolves to "Shape documentation", Foo$qux is not documented, Baz resolves to "Shape documentation", and Foo is not documented.

8.3. examples trait#

Summary
Provides example inputs and outputs for operations.
Trait selector
operation
Value type
list of example structures

Each example trait value is a structure with the following members:

Property Type Description
title string Required. A short title that defines the example.
documentation string A longer description of the example in the CommonMark format.
input document Provides example input parameters for the operation. Each key is the name of a top-level input structure member, and each value is the value of the member.
output document Provides example output parameters for the operation. Each key is the name of a top-level output structure member, and each value is the value of the member.
error ErrorExample structure Provides an error shape ID and example error parameters for the operation.
allowConstraintErrors boolean Set to true to lower input constraint trait validations to warnings. This can only be set when error is provided.

A value for output or error SHOULD be provided. However, both MUST NOT be defined for the same example.

@readonly
operation MyOperation {
    input: MyOperationInput
    output: MyOperationOutput
    errors: [MyOperationError]
}

apply MyOperation @examples([
    {
        title: "Invoke MyOperation"
        input: {
            tags: ["foo", "baz", "bar"]
        }
        output: {
            status: "PENDING"
        }
    }
    {
        title: "Another example for MyOperation"
        input: {
            foo: "baz"
        }
        output: {
            status: "PENDING"
        }
    }
    {
        title: "Error example for MyOperation"
        input: {
            foo: "!"
        }
        error: {
            shapeId: MyOperationError
            content: {
                message: "Invalid 'foo'. Special character not allowed."
            }
        },
        allowConstraintErrors: true
    }
])

8.3.1. ErrorExample structure#

The ErrorExample structure defines an error example using the following members:

Property Type Description
shapeId Shape ID The shape ID of the error in this example. This shape ID MUST be of a structure shape with the error trait. The structure shape MUST be bound as an error to the operation this example trait is applied to.
content document Provides example error parameters for the operation. Each key is the name of a top-level error structure member, and each value is the value of the member.

8.4. externalDocumentation trait#

Summary
Provides named links to external documentation for a shape.
Trait selector
*
Value type
map of string containing a name to string containing a valid URL.
@externalDocumentation(
    "Homepage": "https://www.example.com/"
    "API Reference": "https://www.example.com/api-ref"
)
service MyService {
    version: "2006-03-01"
}

8.5. internal trait#

Summary
Shapes marked with the internal trait are meant only for internal use. Tooling can use the internal trait to filter out shapes from models that are not intended for external customers.
Trait selector
*
Value type
Annotation trait

As an example, a service team may wish to use a version of a model that includes features that are only available to internal customers within the same company, whereas clients for external customers could be built from a filtered version of the model.

structure MyStructure {
    foo: String

    @internal
    bar: String
}

8.7. sensitive trait#

Summary
Indicates that the data stored in the shape is sensitive and MUST be handled with care.
Trait selector

:not(:is(service, operation, resource, member))

Any shape that is not a service, operation, resource, or member.

Value type
Annotation trait

Sensitive data MUST NOT be exposed in things like exception messages or log output. Application of this trait SHOULD NOT affect wire logging (i.e., logging of all data transmitted to and from servers or clients).

@sensitive
string MyString

8.8. since trait#

Summary
Defines the version or date in which a shape or member was added to the model.
Trait selector
*
Value type
string representing the date it was added.

8.9. tags trait#

Summary
Tags a shape with arbitrary tag names that can be used to filter and group shapes in the model.
Trait selector
*
Value type
[string]

Tools can use these tags to filter shapes that should not be visible for a particular consumer of a model. The string values that can be provided to the tags trait are arbitrary and up to the model author.

@tags(["experimental", "public"])
string SomeStructure {}

8.10. title trait#

Summary
Defines a proper name for a service or resource shape. This title can be used in automatically generated documentation and other contexts to provide a user friendly name for services and resources.
Trait selector

:is(service, resource)

Any service or resource

Value type
string
$version: "2"
namespace acme.example

@title("ACME Simple Image Service")
service MySimpleImageService {
    version: "2006-03-01"
}

8.11. unstable trait#

Summary
Indicates a shape is unstable and MAY change in the future. This trait can be applied to trait shapes to indicate that a trait is unstable or experimental. If possible, code generators SHOULD use this trait to warn when code generated from unstable features are used.
Trait selector
*
Value type
Annotation trait
@unstable
string MyString