Data Modeling
DynamoDB Guide
Use the DynamoDB guide when your team wants to document table structure, keys, and indexes in a form that can be reviewed alongside product and architecture context.
Supported input style
The example below uses an AWS-style table definition shape, including:
- table name
- attribute definitions
- primary key schema
- local secondary indexes
- global secondary indexes
- supporting table properties such as TTL or encryption
Example
{
"Type": "AWS::DynamoDB::Table",
"Properties": {
"TableName": "UserData",
"BillingMode": "PAY_PER_REQUEST",
"AttributeDefinitions": [
{ "AttributeName": "PK", "AttributeType": "S" },
{ "AttributeName": "SK", "AttributeType": "S" },
{ "AttributeName": "GSI1PK", "AttributeType": "S" },
{ "AttributeName": "GSI1SK", "AttributeType": "S" },
{ "AttributeName": "SomeField", "AttributeType": "S" }
],
"KeySchema": [
{ "AttributeName": "PK", "KeyType": "HASH" },
{ "AttributeName": "SK", "KeyType": "RANGE" }
],
"LocalSecondaryIndexes": [
{
"IndexName": "LSI1",
"KeySchema": [
{ "AttributeName": "PK", "KeyType": "HASH" },
{ "AttributeName": "SomeField", "KeyType": "RANGE" }
],
"Projection": {
"ProjectionType": "ALL"
}
}
],
"GlobalSecondaryIndexes": [
{
"IndexName": "GSI1",
"KeySchema": [
{ "AttributeName": "GSI1PK", "KeyType": "HASH" },
{ "AttributeName": "GSI1SK", "KeyType": "RANGE" }
],
"Projection": {
"ProjectionType": "ALL"
},
"ProvisionedThroughput": {
"ReadCapacityUnits": 5,
"WriteCapacityUnits": 5
}
}
],
"StreamSpecification": {
"StreamViewType": "NEW_AND_OLD_IMAGES"
},
"TimeToLiveSpecification": {
"AttributeName": "ttl",
"Enabled": true
},
"SSESpecification": {
"SSEEnabled": true,
"SSEType": "KMS",
"KMSMasterKeyId": "alias/aws/dynamodb"
},
"PointInTimeRecoverySpecification": {
"PointInTimeRecoveryEnabled": true
},
"ProvisionedThroughput": {
"ReadCapacityUnits": 5,
"WriteCapacityUnits": 5
},
"DeletionProtectionEnabled": true,
"ContributorInsightsSpecification": {
"Enabled": true
},
"KinesisStreamSpecification": {
"StreamArn": "arn:aws:kinesis:region:account:stream/name"
},
"Tags": [
{ "Key": "env", "Value": "prod" },
{ "Key": "project", "Value": "user-system" }
]
}
}What to model clearly
When documenting DynamoDB structures, make sure readers can quickly identify:
- partition and sort keys
- secondary indexes
- important table settings that affect usage patterns
- the domain meaning of the table, not just its raw infrastructure shape
Recommended usage
- keep source definitions in version control
- update the documented table definition as infrastructure changes
- pair DynamoDB models with service flows and APIs when they are part of a user-facing workflow