19. JSON AST

Smithy models written using the Smithy IDL have an isomorphic JSON abstract syntax tree (AST) representation that can be used to more easily integrate Smithy into languages and tools that do not have a Smithy IDL parser.

• Smithy JSON models can be merged together with other JSON models or other Smithy IDL models using the rules defined in Merging model files.

• All shape IDs in the JSON AST MUST be absolute shape IDs that contain a namespace. One of the main drivers of the simplicity of the JSON AST over the Smithy IDL is that relative and forward references never need to be resolved.

19.1. Top level properties

Smithy JSON models are objects that can contain the following top-level properties:

Property	Type	Description
smithy	string	Required. Defines the version of the Smithy specification (e.g., "2.0"). The version can be set to a single number like "2" or include a point release like "2.0".
metadata	object	Defines all of the metadata about the model using a JSON object. Each key is the metadata key to set, and each value is the metadata value to assign to the key.
shapes	Map<shape ID, AST shape>	A map of absolute shape IDs to shape definitions.

19.2. AST shapes

AST shapes are defined using objects that always contain a type property to define the shape type or apply.

{
    "smithy": "2.0",
    "shapes": {
        "smithy.example#MyString": {
            "type": "string"
        }
    }
}

All entries in the shapes map can contain a traits property that defines the traits attached to the shape. traits is a map where each key is the absolute shape ID of a trait shape and each value is the value to assign to the trait.

{
    "traits": {
        "smithy.example#documentation": "Hi!",
        "smithy.example#tags": [
            "a",
            "b"
        ]
    }
}

The following example defines a string shape with a documentation trait.

{
    "smithy": "2.0",
    "shapes": {
        "smithy.example#MyString": {
            "type": "string",
            "traits": {
                "smithy.api#documentation": "My documentation string"
            }
        }
    }
}

19.3. Simple shapes

Simple shapes are defined as an object. The following example defines a shape for each simple type:

{
    "smithy": "2.0",
    "shapes": {
        "smithy.example#Blob": {
            "type": "blob"
        },
        "smithy.example#Boolean": {
            "type": "boolean"
        },
        "smithy.example#Document": {
            "type": "document"
        },
        "smithy.example#String": {
            "type": "string"
        },
        "smithy.example#Byte": {
            "type": "byte"
        },
        "smithy.example#Short": {
            "type": "short"
        },
        "smithy.example#Integer": {
            "type": "integer"
        },
        "smithy.example#Long": {
            "type": "long"
        },
        "smithy.example#Float": {
            "type": "float"
        },
        "smithy.example#Double": {
            "type": "double"
        },
        "smithy.example#BigInteger": {
            "type": "bigInteger"
        },
        "smithy.example#BigDecimal": {
            "type": "bigDecimal"
        },
        "smithy.example#Timestamp": {
            "type": "timestamp"
        }
    }
}

19.4. List shapes

List shapes have a required member property that is an AST member.

The following example defines a list with a string member:

{
    "smithy": "2.0",
    "shapes": {
        "smithy.example#MyList": {
            "type": "list",
            "member": {
                "target": "smithy.api#String"
            }
        }
    }
}

19.5. AST member

An AST member definition defines a member of a shape. It is a special kind of AST shape reference that also contains an optional traits property that defines traits attached to the member. Each key in the traits property is the absolute shape ID of the trait to apply, and each value is the value to assign to the trait.

{
    "target": "smithy.example#MyShape",
    "traits": {
        "smithy.example#documentation": "Hi!"
    }
}

The following example defines a list shape and its member.

{
    "smithy": "2.0",
    "shapes": {
        "smithy.example#MyList": {
            "type": "list",
            "member": {
                "target": "smithy.api#String",
                "traits": {
                    "smithy.api#documentation": "Member documentation"
                }
            }
        }
    }
}

19.6. AST shape reference

An AST shape reference is an object with a single property, target that maps to an absolute shape ID.

{
    "target": "smithy.example#MyShape"
}

The following example defines a shape reference inside of the operations list of a service shape.

{
    "smithy": "2.0",
    "shapes": {
        "smithy.example#Service": {
            "type": "service",
            "operations": [
                {
                    "target": "smithy.example#Operation"
                }
            ]
        },
        "smithy.example#Operation": {
            "type": "operation"
        }
    }
}

19.7. Map shape

A Map shape has a required key and value AST member. The shape referenced by the key member MUST target a string shape.

The following example defines a map of strings to numbers:

{
    "smithy": "2.0",
    "shapes": {
        "smithy.example#IntegerMap": {
            "type": "map",
            "key": {
                "target": "smithy.api#String"
            },
            "value": {
                "target": "smithy.api#Integer"
            }
        }
    }
}

19.8. Structure, union, enum, and intEnum shapes

Structure, union, enum, and intEnum shapes are defined with a members property that contains a map of member names to AST member definitions. Unions, enums, and intEnums all require at least one member, and a structure shape MAY omit the members property entirely if the structure contains no members.

Each shape's member names MUST be case-insensitively unique across the entire set of members. Each member name MUST adhere to the smithy:Identifier ABNF grammar.

The following example defines a structure with one required and one optional member:

{
    "smithy": "2.0",
    "shapes": {
        "smithy.example#MyStructure": {
            "type": "structure",
            "members": {
                "stringMember": {
                    "target": "smithy.api#String",
                    "traits": {
                        "smithy.api#required": {}
                    }
                },
                "numberMember": {
                    "target": "smithy.api#Integer"
                }
            }
        }
    }
}

The following example defines a union:

{
    "smithy": "2.0",
    "shapes": {
        "smithy.example#MyUnion": {
            "type": "union",
            "members": {
                "a": {
                    "target": "smithy.api#String"
                },
                "b": {
                    "target": "smithy.api#Integer"
                }
            }
        }
    }
}

The following example defines an enum:

{
    "smithy": "2.0",
    "shapes": {
        "smithy.example#MyEnum": {
            "type": "enum",
            "members": {
                "FOO": {
                    "target": "smithy.api#Unit",
                    "traits": {
                        "smithy.api#enumValue": "foo"
                    }
                }
            }
        }
    }
}

The following example defines an intEnum:

{
    "smithy": "2.0",
    "shapes": {
        "smithy.example#MyIntEnum": {
            "type": "intEnum",
            "members": {
                "FOO": {
                    "target": "smithy.api#Unit",
                    "traits": {
                        "smithy.api#enumValue": 1
                    }
                }
            }
        }
    }
}

19.9. Service shape

Service shapes are defined using an object. Service shapes defined in JSON support the same properties as the Smithy IDL.

Property	Type	Description
type	string	service
version	string	Defines the version of the service. The version can be provided in any format (e.g., 2017-02-11, 2.0, etc).
operations	[AST shape reference]	Binds a list of operations to the service. Each reference MUST target an operation.
resources	[AST shape reference]	Binds a list of resources to the service. Each reference MUST target a resource.
errors	[AST shape reference]	Defines a list of common errors that every operation bound within the closure of the service can return. Each provided shape ID MUST target a structure shape that is marked with the error trait.
traits	map of shape ID to trait values	Traits to apply to the service
rename	map of shape ID to string smithy:Identifier	Disambiguates shape name conflicts in the service closure.

{
    "smithy": "2.0",
    "shapes": {
        "smithy.example#MyService": {
            "type": "service",
            "version": "2017-02-11",
            "operations": [
                {
                    "target": "smithy.example#GetServerTime"
                }
            ],
            "resources": [
                {
                    "target": "smithy.example#SomeResource"
                }
            ],
            "errors": [
                {
                    "target": "smithy.example#SomeError"
                }
            ],
            "traits": {
                "smithy.api#documentation": "Documentation for the service"
            },
            "rename": {
                "smithy.example#Widget": "SmithyWidget",
                "foo.example#Widget": "FooWidget"
            }
        }
    }
}

19.10. Resource shape

Resource shapes are defined using an object. Resource shapes defined in JSON support the same properties as the Smithy IDL.

Property	Type	Description
type	string	resource
identifiers	Map<String, AST shape reference>	Defines identifier names and shape IDs used to identify the resource.
properties	Map<String, AST shape reference>	Defines a map of property string names to shape IDs that enumerate the properties of the resource.
create	AST shape reference	Defines the lifecycle operation used to create a resource using one or more identifiers created by the service.
put	AST shape reference	Defines an idempotent lifecycle operation used to create a resource using identifiers provided by the client.
read	AST shape reference	Defines the lifecycle operation used to retrieve the resource.
update	AST shape reference	Defines the lifecycle operation used to update the resource.
delete	AST shape reference	Defines the lifecycle operation used to delete the resource.
list	AST shape reference	Defines the lifecycle operation used to list resources of this type.
operations	[AST shape reference]	Binds a list of non-lifecycle instance operations to the resource. Each reference MUST target an operation.
collectionOperations	[AST shape reference]	Binds a list of non-lifecycle collection operations to the resource. Each reference MUST target an operation.
resources	[AST shape reference]	Binds a list of resources to this resource as a child resource, forming a containment relationship. The resources MUST NOT have a cyclical containment hierarchy, and a resource can not be bound more than once in the entire closure of a resource or service. Each reference MUST target a resource.
traits	Map<shape ID, trait value>	Traits to apply to the resource.

{
    "smithy": "2.0",
    "shapes": {
        "smithy.example#Thing": {
            "type": "resource",
            "identifiers": {
                "forecastId": {
                    "target": "smithy.api#String"
                },
            },
            "create": {
                "target": "smithy.example#CreateThing"
            },
            "read": {
                "target": "smithy.example#GetThing"
            },
            "update": {
                "target": "smithy.example#Updatething"
            },
            "delete": {
                "target": "smithy.example#DeleteThing"
            },
            "list": {
                "target": "smithy.example#ListThings"
            },
            "operations": [
                {
                    "target": "smithy.example#SomeInstanceOperation"
                }
            ],
            "collectionOperations": [
                {
                    "target": "smithy.example#SomeCollectionOperation"
                }
            ],
            "resources": [
                {
                    "target": "smithy.example#SomeResource"
                }
            ]
        }
    }
}

19.11. Operation shape

Operation shapes are defined using an object with the following properties:

Property	Type	Description
type	string	operation
input	AST shape reference	Defines the optional input structure of the operation. The input of an operation MUST resolve to a Structure.
output	AST shape reference	Defines the optional output structure of the operation. The output of an operation MUST resolve to a Structure.
errors	[AST shape reference]	Defines the list of errors that MAY be encountered when invoking the operation. Each reference MUST resolve to a Structure shape that is marked with the error trait trait.
traits	Map<shape ID, trait value>	Traits to apply to the operation.

The following example defines an operation, its input, output, and errors:

{
    "smithy": "2.0",
    "shapes": {
        "smithy.example#MyOperation": {
            "type": "operation",
            "input": {
                "target": "smithy.example#MyOperationInput"
            },
            "output": {
                "target": "smithy.example#MyOperationOutput"
            },
            "errors": [
                {
                    "target": "smithy.example#BadRequestError"
                },
                {
                    "target": "smithy.example#NotFoundError"
                }
            ]
        },
        "smithy.example#MyOperationInput": {
            "type": "structure"
        },
        "smithy.example#MyOperationOutput": {
            "type": "structure"
        },
        "smithy.example#BadRequestError": {
            "type": "structure",
            "traits": {
                "smithy.api#error": "client"
            }
        },
        "smithy.example#NotFoundError": {
            "type": "structure",
            "traits": {
                "smithy.api#error": "client"
            }
        }
    }
}

19.12. Mixins

All shapes in the shapes map can contain a mixins property that defines the Mixins that are added to the shape. mixins is an array of shape references that target shapes marked with the mixin trait.

{
    "smithy": "2.0",
    "shapes": {
        "smithy.example#BaseUser": {
            "type": "structure",
            "members": {
                "userId": {
                    "target": "smithy.api#String"
                }
            },
            "traits": {
                "smithy.api#mixin": {}
            }
        },
        "smithy.example#UserDetails": {
            "type": "structure",
            "members": {
                "username": {
                    "target": "smithy.api#String"
                }
            },
            "mixins": [
                {
                    "target": "smithy.example#BaseUser"
                }
            ]
        }
    }
}

19.13. AST apply type

Traits can be applied to shapes outside of their definition by setting type to apply. The apply type does not actually define a shape for the shape ID; the shape ID MUST reference a shape to which traits are applied. The apply type allows only the traits property.

{
    "smithy": "2.0",
    "shapes": {
        "smithy.example#Struct": {
            "type": "structure",
            "members": {
                "foo": {
                    "target": "smithy.api#String"
                }
            }
        },
        "smithy.example#Struct$foo": {
            "type": "apply",
            "traits": {
                "smithy.api#documentation": "My documentation string"
            }
        }
    }
}