AWS Core Specification¶

sdkId¶

The sdkId property is a required string value that specifies the AWS SDK service ID (e.g., "API Gateway"). This value is used for generating client names in SDKs and for linking between services.

• The value MUST be unique across all AWS services.
• The value must match the following regex: ^[a-zA-Z][a-zA-Z0-9]*( [a-zA-Z0-9]+)*$. To summarize, the value can only contain alphanumeric characters and spaces. However, the first character cannot be a number, and when using spaces, each space must be between two alphanumeric characters.
• The value MUST NOT contain "AWS", "Aws", or "Amazon".
• The value must not case-insensitively end with "API", "Client", or "Service".
• The value MUST NOT change change once a service is publicly released. If the value does change, the service will be considered a brand new service in the AWS SDKs and Tools.

$ aws apigateway

cloudFormationName¶

The cloudFormationName property is a string value that specifies the AWS CloudFormation service name (e.g., ApiGateway). When not set, this value defaults to the name of the service shape. This value is part of the CloudFormation resource type name that is automatically assigned to resources in the service (e.g., AWS::<NAME>::resourceName). This value must match the following regex: ^[A-Z][A-Za-z0-9]+$.

arnNamespace¶

The arnNamespace property is a string value that defines the ARN service namespace of the service (e.g., "apigateway"). This value is used in ARNs assigned to resources in the service. If not set, this value defaults to the lowercase name of the service shape. This value must match the following regex: ^[a-z0-9.\-]{1,63}$.

If not set, this value defaults to the name of the service shape converted to lowercase. This value is combined with resources contained within the service to form ARNs for resources. Only resources that explicitly define the aws.api#arn trait are assigned ARNs, and their relative ARNs are combined with the service's arnNamespace to form an ARN.

cloudTrailEventSource¶

The cloudTrailEventSource property is a string value that defines the eventSource property contained in CloudTrail event records emitted by the service. If not specified, this value defaults to the arnNamespace plus .amazonaws.com. For example:

• AWS CloudFormation has an arnNamespace of cloudformation and an event source of cloudformation.amazonaws.com.
• Amazon EC2 has an arnNamespace of ec2 and an event source of ec2.amazonaws.com.
• Amazon Simple Workflow Service has an arnNamespace of swf and an event source of swf.amazonaws.com.

This convention has some exceptions. For example, the event source for Amazon CloudWatch is monitoring.amazonaws.com. Such services will need to explicitly configure the cloudTrailEventSource setting.

abbreviation¶

The abbreviation property is a string value that defines the official abbreviation of a service. For example, the official abbreviation of "Amazon Simple Storage Service" is "Amazon S3", and the abbreviation of "Amazon Kinesis Firehose" is "Firehose".

See Appendix A: Example SDK service IDs for a table containing various AWS services and their abbreviations.

Format of an ARN¶

An ARN is is a structured URI made up of the following components:

arn:partition:service:region:account-id:resource
                         \       /
                     Both are optional

partition

The partition that the resource is in. For standard AWS regions, the partition is "aws". If you have resources in other partitions, the partition is aws-partitionname. For example, the partition for resources in the China (Beijing) region is aws-cn.

service

The service namespace that identifies the AWS product (for example, Amazon S3 is "s3", IAM is "iam", and Amazon RDS is "rds"). For a list of namespaces, see AWS Service Namespaces. The namespace used by Smithy services is defined by the arnNamespace property of the aws.api#service trait.

region

The region the resource resides in. Note that the ARNs for some resources do not require a region, so this component MAY be omitted.

account-id

The ID of the AWS account that owns the resource, without the hyphens. For example, 123456789012. Note that the ARNs for some resources don't require an account number, so this component MAY be omitted.

resource

Defines a specific resource within a service. The content of this segment of an ARN varies by service. It often includes an indicator of the type of resource—for example, an IAM user or Amazon RDS database —followed by a slash (/) or a colon (:), followed by the resource name itself. Some services allow paths for resource names, as described in Paths in ARNs.

Some example ARNs from various services include:

// Elastic Beanstalk application version
arn:aws:elasticbeanstalk:us-east-1:123456789012:environment/My App/MyEnvironment

// IAM user name
arn:aws:iam::123456789012:user/David

// Amazon RDS instance used for tagging
arn:aws:rds:eu-west-1:123456789012:db:mysql-db

// Object in an Amazon S3 bucket
arn:aws:s3:::my_corporate_bucket/exampleobject.png

Relative ARN templates¶

arn traits with relative templates are combined with the service to form an absolute ARN template. This ARN template can only be expanded at runtime with actual values for the partition, region name, account ID, and identifier label placeholders.

For example, given the following service:

namespace aws.fooBaz

use aws.api#service
use aws.api#arn

@service(sdkId: "Some Value")
service FooBaz {
    version: "2018-03-17",
    resources: [MyResource],
}

@arn(template: "myresource/{myId}")
resource MyResource {
    identifiers: {myId: MyResourceId},
}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#FooBaz": {
            "type": "service",
            "version": "2018-03-17",
            "resources": [
                {
                    "target": "smithy.example#MyResource"
                }
            ],
            "traits": {
                "aws.api#service": {
                    "sdkId": "Some Value"
                }
            }
        },
        "smithy.example#MyResource": {
            "type": "resource",
            "identifiers": {
                "myId": {
                    "target": "smithy.example#MyResourceId"
                }
            },
            "traits": {
                "aws.api#arn": {
                    "template": "myresource/{myId}"
                }
            }
        }
    }
}

The ARN template assigned to MyResource when used with the FooBaz service expands to arn:{AWS::partition}:myservice:{AWS::Region}:{AWS::AccountId}:myresource/{myId} at runtime. The label {myId} indicates that the value of the resource's identifier is to be inserted into the ARN template when resolving it at runtime.

Using an ARN as a resource identifier¶

Absolute ARN templates are used to provide an entire ARN to a resource that is not combined with the service ARN namespace. When a resource uses an ARN as its identifier, an absolute ARN template MUST be defined on the resource that uses a placeholder containing the name of the identifier of the resource.

use aws.api#arn
use aws.api#arnReference

@arn(template: "{arn}", absolute: true)
resource MyResource {
    identifiers: {arn: Arn}
}

@arnReference(service: FooBaz, resource: MyResource)
string Arn

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#MyResource": {
            "type": "resource",
            "identifiers": {
                "arn": {
                    "target": "smithy.example#Arn"
                }
            },
            "traits": {
                "aws.api#arn": {
                    "template": "{arn}",
                    "absolute": true
                }
            }
        },
        "smithy.example#Arn": {
            "type": "string",
            "traits": {
                "aws.api#arnReference": {
                    "service": "FooBaz",
                    "resource": "MyResource"
                }
            }
        }
    }
}

Data Classifications¶

The following table describes the available data classifications that can be applied through the aws.api#data trait.

Unsigned Payloads and signature version 4¶

Using an unsigned payload with AWS signature version 4 requires that the literal string UNSIGNED-PAYLOAD is used when constructing a canonical request, and the same value is sent in the x-amz-content-sha256 header when sending an HTTP request.

aws.api#clientEndpointDiscovery trait¶

Trait summary

The clientEndpointDiscovery trait indicates the operation that the client should use to discover endpoints for the service and the error returned when the endpoint being accessed has expired.

Trait selector

service

Trait value

structure

The aws.api#clientEndpointDiscovery trait is a structure that supports the following members:

The input of the operation targeted by operation MAY contain none, either, or both of the following members:

• a string member named Operation
• a map member named Identifiers whose key and value types are string types.

The operation output MUST contain a member Endpoints that is a list of Endpoint structures, which are made up of two members:

• a string member named Address
• a long member named CachePeriodInMinutes

aws.api#clientDiscoveredEndpoint trait¶

Trait summary

The clientDiscoveredEndpoint trait indicates that the target operation should use the client's endpoint discovery logic.

Trait selector

operation

Trait value

structure

The aws.api#clientDiscoveredEndpoint trait is a structure that supports the following members:

aws.clientEndpointDiscoveryId trait¶

Summary

The clientEndpointDiscoveryId trait indicates which member(s) of the operation input should be used to discover an endpoint for the service.

Trait selector

operation[trait|aws.api#clientDiscoveredEndpoint] -[input]-> structure > :test(member[trait|required] > string)

Trait value

Annotation trait

Example Model¶

The following model illustrates an API that uses a DescribeEndpoints operation to perform endpoint discovery for a GetObject operation using an clientEndpointDiscoveryId.

@aws.api#clientEndpointDiscovery(
    operation: DescribeEndpoints,
    error: InvalidEndpointError,
)
service FooService {
  version: "2019-09-10",
  operations: [DescribeEndpoints, GetObject]
}

operation DescribeEndpoints {
    input: DescribeEndpointsInput,
    output: DescribeEndpointsOutput,
    errors: [InvalidEndpointError]
}

@error("client")
@httpError(421)
structure InvalidEndpointError {}

structure DescribeEndpointsInput {
  Operation: String,
  Identifiers: Identifiers,
}

map Identifiers {
  key: String,
  value: String
}

structure DescribeEndpointsOutput {
  Endpoints: Endpoints,
}

list Endpoints {
  member: Endpoint
}

structure Endpoint {
  Address: String,
  CachePeriodInMinutes: Long,
}

@aws.api#clientDiscoveredEndpoint(required: true)
operation GetObject {
    input: GetObjectInput,
    output: GetObjectOutput
}

structure GetObjectInput {
  @clientEndpointDiscoveryId
  @required
  Id: String,
}

structure GetObjectOutput {
  Object: Blob,
}

{
    "smithy": "0.5.0",
    "shapes": {
        "ns.foo#FooService": {
            "type": "service",
            "version": "2019-09-10",
            "operations": [
                {
                    "target": "ns.foo#DescribeEndpoints"
                },
                {
                    "target": "ns.foo#GetObject"
                }
            ],
            "traits": {
                "aws.api#clientEndpointDiscovery": {
                    "operation": "ns.foo#DescribeEndpoints",
                    "error": "InvalidEndpointError"
                }
            }
        },
        "ns.foo#DescribeEndpoints": {
            "type": "operation",
            "input": {
                "target": "ns.foo#DescribeEndpointsInput"
            },
            "output": {
                "target": "ns.foo#DescribeEndpointsOutput"
            }
        },
        "ns.foo#DescribeEndpointsInput": {
            "type": "structure",
            "members": {
                "Operation": {
                    "target": "smithy.api#String"
                },
                "Identifiers": {
                    "target": "ns.foo#Identifiers"
                }
            }
        },
        "ns.foo#Identifiers": {
            "type": "map",
            "key": {
                "target": "smithy.api#String"
            },
            "value": {
                "target": "smithy.api#String"
            }
        },
        "ns.foo#DescribeEndpointsOutput": {
            "type": "structure",
            "members": {
                "Endpoints": {
                    "target": "ns.foo#Endpoints"
                }
            }
        },
        "ns.foo#Endpoints": {
            "type": "list",
            "member": {
                "target": "ns.foo#Endpoint"
            }
        },
        "ns.foo#Endpoint": {
            "type": "structure",
            "members": {
                "Address": {
                    "target": "smithy.api#String"
                },
                "CachePeriodInMinutes": {
                    "target": "smithy.api#Long"
                }
            }
        },
        "ns.foo#GetObject": {
            "type": "operation",
            "input": {
                "target": "ns.foo#GetObjectInput"
            },
            "output": {
                "target": "ns.foo#GetObjectOutput"
            },
            "errors": [
                {
                    "target": "ns.foo#InvalidEndpointError"
                }
            ],
            "traits": {
                "aws.api#clientDiscoveredEndpoint": {
                    "required": true
                }
            }
        },
        "ns.foo#GetObjectInput": {
            "type": "structure",
            "members": {
                "Id": {
                    "target": "smithy.api#String",
                    "traits": {
                        "aws.api#clientEndpointDiscoveryId": true,
                        "smithy.api#required": true
                    }
                }
            }
        },
        "ns.foo#GetObjectOutput": {
            "type": "structure",
            "members": {
                "Object": {
                    "target": "smithy.api#Blob"
                }
            }
        },
        "ns.foo#InvalidEndpointError": {
            "type": "structure",
            "traits": {
                "smithy.api#error": "client",
                "smithy.api#httpError": 421
            }
        }
    }
}

Client Behavior¶

When a client calls an operation which has the clientDiscoveredEndpoint trait where required is set to true or where the client has explicitly enabled endpoint discovery, the client MUST attempt to perform endpoint discovery synchronously.

When a client calls an operation which has the clientDiscoveredEndpoint trait where required is set to false, the client SHOULD attempt to perform endpoint discovery asynchronously.

To perform endpoint discovery, the client MUST first make a request to the operation targeted by the value of operation on the service's clientEndpointDiscovery trait or attempt to retrieve a previously cached response.

When calling the endpoint operation, the client MUST provide the following parameters if they are in the endpoint operation's input shape:

• Operation - the name of the client operation to be called.
• Identifiers - a map of member name to member value of all members in the client operation's input shape that have the clientEndpointDiscoveryId trait.

The client MUST then use an endpoint from the Endpoints list in the response. The client SHOULD prioritize endpoints by the order in which they appear in the list.

aws.v4 Authentication¶

The aws.v4 authentication scheme is used to indicate that a service supports AWS signature version 4. This authentication scheme does not require any configuration settings. The service name used in the signature version 4 credential scope defaults to the resolved value of the aws.api#service trait arnNamespace property (that is, if the value is explicitly defined, then use it, otherwise use the name of the service converted to lowercase characters).

namespace aws.fooBaz

use aws.api#service

@service(sdkId: "Some Value")
@protocols([{name: "aws.rest-json", auth: ["aws.v4"]}])
service FooBaz {
    version: "2018-03-17",
}

{
    "smithy": "0.5.0",
    "shapes": {
        "aws.fooBaz#FooBaz": {
            "type": "service",
            "version": "2018-03-17",
            "traits": {
                "smithy.api#protocols": [
                    {
                        "name": "aws.rest-json",
                        "auth": [
                            "aws.v4"
                        ]
                    }
                ],
                "aws.api#service": {
                    "sdkId": "Some Value"
                }
            }
        }
    }
}

Appendix A: Example SDK service IDs¶

The following, non-exhaustive, table defines the SDK service ID of many existing AWS services.