18. Smithy IDL#

Smithy models are defined using either the Smithy interface definition language (IDL) or the JSON abstract syntax tree (AST). This document defines the ABNF grammar and syntax for defining models with the Smithy IDL.

18.1. Smithy IDL overview#

The Smithy IDL is made up of 3, ordered sections, each of which is optional:

Control section; defines parser directives like which version of the IDL to use.
Metadata section; applies metadata to the entire model.
Shape section; where shapes and traits are defined. A namespace MUST be defined before any shapes or traits can be defined. smithy:UseStatements can be defined after a namespace and before shapes or traits to refer to shapes in other namespaces using a shorter name.

The following example defines a model file with each section:

Smithy

// (1) Control section
$version: "2"

// (2) Metadata section
metadata foo = "bar"

// (3) Shape section
namespace smithy.example

use smithy.other.namespace#MyString

structure MyStructure {
    @required
    foo: MyString
}

JSON

{
    "smithy": "2",
    "metadata": {
        "foo": "bar"
    },
    "shapes": {
        "smithy.example#MyStructure": {
            "type": "structure",
            "members": {
                "foo": {
                    "target": "smithy.other.namespace#MyString",
                    "traits": {
                        "smithy.api#required": {}
                    }
                }
            }
        }
    }
}

18.2. Lexical notes#

Smithy models MUST be encoded using UTF-8 and SHOULD use Unix style line endings (\n).
The Smithy ABNF is whitespace sensitive.
Except for within strings, commas in the Smithy IDL are considered whitespace. Commas can be used anywhere where they make the model easier to read (for example, in complex traits defined on a single line).

18.3. Smithy IDL ABNF#

The Smithy IDL is defined by the following ABNF which uses case-sensitive string support defined in RFC 7405.

idl =
    [WS] ControlSection MetadataSection ShapeSection

Whitespace

WS =
    1*(SP / NL / Comment / Comma) ; whitespace

Comma =
    ","

SP =
    1*(%x20 / %x09) ; one or more spaces or tabs

NL =
    %x0A / %x0D.0A ; Newline: \n and \r\n

NotNL =
    %x09 / %x20-10FFFF ; Any character except newline

BR =
    [SP] 1*(Comment / NL) [WS]; line break followed by whitespace

Comments

Comment =
    DocumentationComment / LineComment

DocumentationComment =
    "///" *NotNL NL

LineComment =
    "//" [(%x09 / %x20-2E / %x30-10FFF) *NotNL] NL
    ; First character after "//" can't be "/"

Control

ControlSection =
    *(ControlStatement)

ControlStatement =
    "$" NodeObjectKey [SP] ":" [SP] NodeValue BR

Metadata

MetadataSection =
    *(MetadataStatement)

MetadataStatement =
    %s"metadata" SP NodeObjectKey [SP] "=" [SP] NodeValue BR

Node values

NodeValue =
    NodeArray
  / NodeObject
  / Number
  / NodeKeyword
  / NodeStringValue

NodeArray =
    "[" [WS] *(NodeValue [WS]) "]"

NodeObject =
    "{" [WS] [NodeObjectKvp *(WS NodeObjectKvp)] [WS] "}"

NodeObjectKvp =
    NodeObjectKey [WS] ":" [WS] NodeValue

NodeObjectKey =
    QuotedText / Identifier

Number =
    [Minus] Int [Frac] [Exp]

DecimalPoint =
    %x2E ; .

DigitOneToNine =
    %x31-39 ; 1-9

E =
    %x65 / %x45 ; e E

Exp =
    E [Minus / Plus] 1*DIGIT

Frac =
    DecimalPoint 1*DIGIT

Int =
    Zero / (DigitOneToNine *DIGIT)

Minus =
    %x2D ; -

Plus =
    %x2B ; +

Zero =
    %x30 ; 0

NodeKeyword =
    %s"true" / %s"false" / %s"null"

NodeStringValue =
    ShapeId / TextBlock / QuotedText

QuotedText =
    DQUOTE *QuotedChar DQUOTE

QuotedChar =
    %x09        ; tab
  / %x20-21     ; space - "!"
  / %x23-5B     ; "#" - "["
  / %x5D-10FFFF ; "]"+
  / EscapedChar
  / NL

EscapedChar =
    Escape (Escape / DQUOTE / %s"b" / %s"f"
             / %s"n" / %s"r" / %s"t" / "/"
             / UnicodeEscape)

UnicodeEscape =
    %s"u" Hex Hex Hex Hex

Hex =
    DIGIT / %x41-46 / %x61-66

Escape =
    %x5C ; backslash

TextBlock =
    ThreeDquotes [SP] NL *TextBlockContent ThreeDquotes

TextBlockContent =
    QuotedChar / (1*2DQUOTE 1*QuotedChar)

ThreeDquotes =
    DQUOTE DQUOTE DQUOTE

Shapes

ShapeSection =
    [NamespaceStatement UseSection [ShapeStatements]]

NamespaceStatement =
    %s"namespace" SP Namespace BR

UseSection =
    *(UseStatement)

UseStatement =
    %s"use" SP AbsoluteRootShapeId BR

ShapeStatements =
    ShapeOrApplyStatement *(BR ShapeOrApplyStatement)

ShapeOrApplyStatement =
    ShapeStatement / ApplyStatement

ShapeStatement =
    TraitStatements Shape

Shape =
    SimpleShape
  / EnumShape
  / AggregateShape
  / EntityShape
  / OperationShape

SimpleShape =
    SimpleTypeName SP Identifier [Mixins]

SimpleTypeName =
    %s"blob" / %s"boolean" / %s"document" / %s"string"
  / %s"byte" / %s"short" / %s"integer" / %s"long"
  / %s"float" / %s"double" / %s"bigInteger"
  / %s"bigDecimal" / %s"timestamp"

Mixins =
    [SP] %s"with" [WS] "[" [WS] 1*(ShapeId [WS]) "]"

EnumShape =
    EnumTypeName SP Identifier [Mixins] [WS] EnumShapeMembers

EnumTypeName =
    %s"enum" / %s"intEnum"

EnumShapeMembers =
    "{" [WS] 1*(EnumShapeMember [WS]) "}"

EnumShapeMember =
    TraitStatements Identifier [ValueAssignment]

ValueAssignment =
    [SP] "=" [SP] NodeValue [SP] [Comma] BR

AggregateShape =
    AggregateTypeName SP Identifier [ForResource] [Mixins]
     [WS] ShapeMembers

AggregateTypeName =
    %s"list" / %s"map" / %s"union" / %s"structure"

ForResource =
    SP %s"for" SP ShapeId

ShapeMembers =
    "{" [WS] *(ShapeMember [WS]) "}"

ShapeMember =
    TraitStatements (ExplicitShapeMember / ElidedShapeMember)
     [ValueAssignment]

ExplicitShapeMember =
    Identifier [SP] ":" [SP] ShapeId

ElidedShapeMember =
    "$" Identifier

EntityShape =
    EntityTypeName SP Identifier [Mixins] [WS] NodeObject

EntityTypeName =
    %s"service" / %s"resource"

OperationShape =
    %s"operation" SP Identifier [Mixins] [WS] OperationBody

OperationBody =
    "{" [WS] *(OperationProperty [WS]) "}"

OperationProperty =
    OperationInput / OperationOutput / OperationErrors

OperationInput =
    %s"input" [WS] (InlineAggregateShape / (":" [WS] ShapeId))

OperationOutput =
    %s"output" [WS] (InlineAggregateShape / (":" [WS] ShapeId))

OperationErrors =
    %s"errors" [WS] ":" [WS] "[" [WS] *(ShapeId [WS]) "]"

InlineAggregateShape =
    ":=" [WS] TraitStatements [ForResource] [Mixins]
     [WS] ShapeMembers

Traits

TraitStatements =
    *(Trait [WS])

Trait =
    "@" ShapeId [TraitBody]

TraitBody =
    "(" [WS] [TraitStructure / TraitNode] ")"

TraitStructure =
    1*(NodeObjectKvp [WS])

TraitNode =
    NodeValue [WS]

ApplyStatement =
    ApplyStatementSingular / ApplyStatementBlock

ApplyStatementSingular =
    %s"apply" SP ShapeId WS Trait

ApplyStatementBlock =
    %s"apply" SP ShapeId WS "{" [WS] TraitStatements "}"

Shape ID

18.4. Comments#

A comment can appear at any place between tokens where whitespace (smithy:WS) can appear. Comments in Smithy are defined using two forward slashes followed by any character. A newline terminates a comment.

$version: "2"

// This is a comment
namespace com.foo // This is also a comment

// Another comment
string MyString

Note

Three forward slashes can be used to define the documentation of a shape using a special documentation comment.

18.5. Control section#

The control section of a model contains control statements that apply parser directives to a specific IDL file. Because control statements influence parsing, they MUST appear at the beginning of a file before any other statements and have no effect on the semantic model.

The following control statements are currently supported:

Name	Type	Description
version	string	Defines the version of the Smithy IDL used in the model file.
operationInputSuffix	string	Defines the suffix used when generating names for inline operation input.
operationOutputSuffix	string	Defines the suffix used when generating names for inline operation output.

Implementations MUST ignore unknown control statements.

18.5.1. Version statement#

The Smithy specification is versioned using a major . minor versioning scheme. A version requirement is specified for a model file using the $version control statement. When no version number is specified in the IDL, an implementation SHOULD assume that the model can be loaded. Because this can lead to unexpected parsing errors, models SHOULD always include a version.

The value provided in a version control statement is a string that MUST adhere to the following ABNF:

version_string =
    1*DIGIT [ "." 1*DIGIT ]

The following example sets the version to 2, meaning that tooling MUST support a version greater than or equal to 2.0 and less than 3.0:

Smithy

$version: "2"

JSON

{
    "smithy": "2"
}

A minor version SHOULD be provided when a model depends on a feature released in a minor update of the specification. The following example sets the version requirement of a file to 2.1, meaning that tooling MUST support a version greater than or equal to 2.1 and less than 3.0:

Smithy

$version: "2.1"

JSON

{
    "smithy": "2.1"
}

Version compatibility

A single version statement can appear in a model file, but different versions MAY be encountered when merging multiple model files together. Multiple versions are supported if and only if all of the version statements are supported by the tool loading the models.

18.6. Metadata section#

The metadata section is used to apply untyped metadata to the entire model. A smithy:MetadataStatement consists of the metadata key to set, followed by =, followed by the node value to assign to the key.

The following example defines metadata in the model:

Smithy

$version: "2"
metadata greeting = "hello"
metadata "stringList" = ["a", "b", "c"]

JSON

{
    "smithy": "2",
    "metadata": {
        "greeting": "hello",
        "stringList": ["a", "b", "c"]
    }
}

Metadata is not defined within a namespace. Unquoted object property values are considered syntactic shape IDs and resolve to the prelude namespace, smithy.api.

The following Smithy IDL model:

$version: "2"
metadata exampleSyntacticShapeId = required

Is equivalent to the following JSON AST model:

{
    "smithy": "2",
    "metadata": {
        "exampleSyntacticShapeId": "smithy.api#required"
    }
}

18.8. Node values#

Node values are analogous to JSON values. Node values are used to define metadata and trait values. Smithy's node values have many advantages over JSON: comments, unquoted keys, unquoted strings, text blocks, and trailing commas.

The following example defines a complex object metadata entry using a node value:

metadata foo = {
    hello: 123,
    "foo": "456",
    testing: """
        Hello!
        """,
    an_array: [10.5],
    nested-object: {
        hello-there$: true
    }, // <-- Trailing comma
}

Array node

An array node is defined like a JSON array. A smithy:NodeArray contains zero or more heterogeneous smithy:NodeValues. A trailing comma is allowed in a NodeArray.

The following examples define arrays with zero, one, and two values:

[]
[true]
[1, "hello",]

Object node

An object node is defined like a JSON object. A smithy:NodeObject contains zero or more key value pairs of strings (a smithy:NodeObjectKey) that map to heterogeneous smithy:NodeValues. A trailing comma is allowed in a NodeObject.

The following examples define objects with zero, one, and two key value pairs:

{}
{foo: true}
{foo: "hello", "bar": [1, 2, {}]}

Number node

A node smithy:Number contains numeric data. It is defined like a JSON number. The following examples define several Number values:

0
0.0
1234
-1234.1234
1e+2
1.0e-10

Node keywords

Several keywords are used when parsing smithy:NodeValue.

true: The value is treated as a boolean true
false: The value is treated as a boolean false
null: The value is treated like a JSON null

18.8.1. String values#

A NodeValue can contain smithy:NodeStringValue productions that all define strings.

New lines

New lines in strings are normalized from CR (u000D) and CRLF (u000Du000A) to LF (u000A). This ensures that strings defined in a Smithy model are equivalent across platforms. If a literal \r is desired, it can be added a string value using the Unicode escape \u000d.

String equivalence

The NodeStringValue production defines several productions used to define strings, and in order for these productions to work in concert with the JSON AST format, each of these production MUST be treated like equivalent string values when loaded into the semantic model.

18.8.2. String escape characters#

The Smithy IDL supports escape sequences only within quoted strings. The following escape sequences are allowed:

Unicode code point	Escape	Meaning
U+0022	`\"`	double quote
U+005C	`\\`	backslash
U+002F	`\/`	forward slash
U+0008	`\b`	backspace BS
U+000C	`\f`	form feed FF
U+000A	`\n`	line feed LF
U+000D	`\r`	carriage return CR
U+0009	`\t`	horizontal tab HT
U+HHHH	`\uHHHH`	4-digit hexadecimal Unicode code point
nothing	`\\r\n`, `\\r`, `\\n`	escaped new line expands to nothing

Any other sequence following a backslash is an error.

18.8.3. Text blocks#

A text block is a string literal that can span multiple lines and automatically removes any incidental whitespace. Smithy text blocks are heavily inspired by text blocks defined in JEP 355.

A text block is opened with three double quotes ("""), followed by a newline, zero or more content characters, and closed with three double quotes. Text blocks differentiate incidental whitespace from significant whitespace. Smithy will re-indent the content of a text block by removing all incidental whitespace.

@documentation("""
    <div>
        <p>Hello!</p>
    </div>
    """)

The four leading spaces in the above text block are considered insignificant because they are common across all lines. Because the closing delimiter appears on its own line, a trailing new line is added to the result. The content of the text block is re-indented to remove the insignificant whitespace, making it equivalent to the following:

@documentation("<div>\n    <p>Hello!</p>\n</div>\n")

The closing delimiter can be placed on the same line as content if no new line is desired at the end of the result. The above example could be rewritten to not including a trailing new line:

@documentation("""
    <div>
        <p>Hello!</p>
    </div>""")

This example is equivalent to the following:

@documentation("<div>\n    <p>Hello!</p>\n</div>")

The following text blocks are ill-formed:

"""foo"""  // missing new line following open delimiter
""" """    // missing new line following open delimiter
"""
"          // missing closing delimiter

18.8.3.1. Incidental white space removal#

Smithy will re-indent the content of a text block by removing all incidental whitespace using the following algorithm:

Split the content of the text block at every LF, producing a list of lines. The opening LF of the text block is not considered.

Given the following example ("." is used to represent spaces),
```
@documentation("""
....Foo
........Baz

..
....Bar
....""")
```
the following lines are produced:
```
["    Foo", "        Baz", "", "  ", "    Bar", "    "]
```
Compute the common whitespace prefix by iterating over each line, counting the number of leading spaces (" ") and taking the minimum count. Except for the last line of content, lines that are empty or consist wholly of whitespace are not considered. If the last line of content (that is, the line that contains the closing delimiter) appears on its own line, then that line's leading whitespace is considered when determining the common whitespace prefix, allowing the closing delimiter to determine the amount of indentation to remove.

Using the previous example, the common whitespace prefix is four spaces. The empty third line and the blank fourth lines are not considered when computing the common whitespace. The following uses "." to represent the common whitespace prefix:
```
@documentation("""
....Foo
....    Baz

....
....Bar
....""")
```
Remove the common white space prefix from each line.

This step produces the following values from the previous example:
```
["Foo", "    Baz", "", "", "Bar", ""]
```
Remove any trailing spaces from each line.
Concatenate each line together, separated by LF.

This step produces the following result ("|" is used to represent the left margin):
```
|Foo
|    Baz
|
|
|Bar
|
```

18.8.3.2. Significant trailing line#

The last line of text block content is used when determining the common whitespace prefix.

Consider the following example:

@documentation("""
    Foo
        Baz
    Bar
""")

Because the closing delimiter is at the margin and left of the rest of the content, the common whitespace prefix is 0 characters, resulting in the following equivalent string:

@documentation("    Foo\n        Baz\n    Bar\n")

If the closing delimiter is moved to the right of the content, then it has no bearing on the common whitespace prefix. The common whitespace prefix in the following example is visualized using "." to represent spaces:

@documentation("""
....Foo
....    Baz
....Bar
        """)

Because lines are trimmed when they are added to the result, the above example is equivalent to the following:

@documentation("Foo\n    Baz\nBar\n")

18.8.3.3. Escapes in text blocks#

Text blocks support all of the string escape characters of other strings. The use of three double quotes allows unescaped double quotes (") to appear in text blocks. The following text block is interpreted as "hello!":

"""
"hello!"
"""

Three quotes can appear in a text block without being treated as the closing delimiter as long as one of the quotes are escaped. The following text block is interpreted as foo """\nbaz:

"""
foo \"""
baz"""

String escapes are interpreted after incidental whitespace is removed from a text block. The following example uses "." to denote spaces:

"""
..<div>
....<p>Hi\n....bar</p>
..</div>
.."""

Because string escapes are expanded after incidental whitespace is removed, it is interpreted as:

<div>
..<p>Hi
....bar</p>
</div>

New lines in the text block can be escaped. This allows for long, single-line strings to be broken into multiple lines in the IDL. The following example is interpreted as Foo Baz Bam:

"""
Foo \
Baz \
Bam"""

Escaped new lines can be intermixed with unescaped newlines. The following example is interpreted as Foo\nBaz Bam:

"""
Foo
Baz \
Bam"""

18. Smithy IDL#

18.1. Smithy IDL overview#

18.2. Lexical notes#

18.3. Smithy IDL ABNF#

18.4. Comments#

18.5. Control section#

18.5.1. Version statement#

18.6. Metadata section#

18.7. Shape section#

18.7.1. Namespaces#

18.7.2. Referring to shapes#

18.7.2.1. Relative shape ID resolution#

18.7.2.2. Syntactic shape IDs#

18.7.3. Defining shapes#

18.7.3.1. Simple shapes#

18.7.3.2. Enum shapes#

18.7.3.3. IntEnum shapes#

18.7.3.4. List shapes#

18.7.3.5. Map shapes#

18.7.3.6. Structure shapes#

18.7.3.7. Union shapes#

18.7.3.8. Service shape#

18.7.3.9. Operation shape#

18.7.3.9.1. Inline input / output shapes#

18.7.3.10. Resource shape#

18.7.3.11. Mixins#

18.7.3.12. Target Elision#

18.7.4. Documentation comment#

18.7.5. Applying traits#

18.7.5.1. Trait values#

18.7.5.2. Structure, map, and union trait value syntax#

18.7.5.3. Omitted trait values#

18.7.5.4. Apply statement#

18.8. Node values#

18.8.1. String values#

18.8.2. String escape characters#

18.8.3. Text blocks#

18.8.3.1. Incidental white space removal#

18.8.3.2. Significant trailing line#

18.8.3.3. Escapes in text blocks#