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:

Use the documentation trait of the shape, if present.
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.6. `recommended` trait¶

Summary

Indicates that a structure member SHOULD be set. This trait is useful when the majority of use cases for a structure benefit from providing a value for a member, but the member is not actually required or cannot be made required backward compatibly.

Trait selector

structure > member

Value type

Structure with the following members:

Property	Type	Description
reason	`string`	Provides a reason why the member is recommended.

Conflicts with

required trait

@input
structure PutContentsInput {
    @required
    contents: String

    @recommended(reason: "Validation will reject contents if they are invalid.")
    validateContents: Boolean
}

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 shape. This title can be used in automatically generated documentation and other contexts to provide a user friendly name for a shape.

Trait selector

:not(member)

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

8. Documentation traits¶

8.1. deprecated trait¶

8.2. documentation trait¶

8.2.1. Effective documentation¶

8.3. examples trait¶

8.3.1. ErrorExample structure¶

8.4. externalDocumentation trait¶

8.5. internal trait¶

8.6. recommended trait¶

8.7. sensitive trait¶

8.8. since trait¶

8.9. tags trait¶

8.10. title trait¶

8.11. unstable trait¶

8.1. `deprecated` trait¶

8.2. `documentation` trait¶

8.3. `examples` trait¶

8.3.1. `ErrorExample` structure¶

8.4. `externalDocumentation` trait¶

8.5. `internal` trait¶

8.6. `recommended` trait¶

8.7. `sensitive` trait¶

8.8. `since` trait¶

8.9. `tags` trait¶

8.10. `title` trait¶

8.11. `unstable` trait¶