Skip to main content
POST
Required scope: schemas:write
Before creating a schema, follow the IAM Setup guide to configure the trust policy and permissions DynamoSQL needs to assume your role. After creating a schema, use Validate Role to confirm the configuration is correct.

Authorizations

​
Authorization
string
header
required

Bearer token obtained from POST /v1/auth/token. Pass in the Authorization header as Bearer <token>.

Body

application/json
​
schemaName
string
required

Logical name for this schema. Used in SQL as the schema qualifier: SELECT * FROM {schemaName}.{tableName}. Must be unique within the tenant. Case-insensitive at query time; stored as-provided.

Example:

"myschema"

​
region
string
required

AWS region where the DynamoDB tables reside. Must be a valid AWS region identifier (e.g., us-east-1, eu-west-2).

Example:

"us-east-1"

​
accountId
string
required

12-digit AWS account ID that owns the DynamoDB tables.

Example:

"123456789012"

​
roleArn
string
required

Full ARN of the IAM role to assume. The role must have a trust policy permitting DynamoSQL to assume it with the provided externalId. See the IAM Setup guide for the required trust policy and permission set.

Example:

"arn:aws:iam::123456789012:role/DynamoSQLReadRole"

​
externalId
string
required

External ID to include in sts:AssumeRole. Must match the sts:ExternalId condition in the role's trust policy. Generate a random string (UUID recommended) and store it in both DynamoSQL and your IAM role.

Example:

"dsql-ext-7f3a9c2b"

​
tableAllowlist
string[]

Optional list of DynamoDB table names this schema may access. Omit to allow all tables visible to the role. Pass ["*"] to explicitly allow all tables with wildcard validation. Individual names are matched exactly (case-sensitive).

Example:

Response

Schema created. A background metadata refresh has been started.

​
success
boolean
required

true when the request was processed without errors, false otherwise. Always present.

​
data
object

A DynamoSQL schema record. A schema connects a logical name to the IAM role and AWS region DynamoSQL uses to access DynamoDB on your behalf via cross-account role assumption.

​
error
object

Present in the response body when success is false.