Smithy specification#

This is the specification of Smithy 2.0, an interface definition language and set of tools used to build clients, servers, and other kinds of artifacts through model transformations.

Conventions used in this document

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. This specification makes use of the Augmented Backus-Naur Form (ABNF) RFC 5234 notation, including the core rules defined in Appendix B of that document.

Please report technical errors and ambiguities in this specification to the Smithy GitHub repository at This specification is open source; contributions are welcome.


Unless declared otherwise, example Smithy models given in this specification are written using the Smithy interface definition language (IDL) syntax. Complementary JSON AST examples are provided alongside Smithy IDL examples where appropriate.

Table of contents