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
ofstring
containing a name tostring
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 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