AWS has recently announced the public availability of its definitive API models, publishing daily updates to Maven Central and providing open-source access via a new GitHub repository.
These resources contain Smithy API models, which define AWS’s public interface, operations, behaviors, and error types, moving beyond their internal use for SDK and CLI generation. Smithy is a protocol-agnostic interface definition language and set of tools for generating clients, servers, and documentation for any programming language.
Since 2018, AWS has internally used Smithy models to generate its SDK clients and CLI tools. By making these models publicly accessible, AWS aims to provide a broader ecosystem for development and integration. With this initiative, developers can, according to the company:
- Generate custom SDK clients: Build purpose-built SDKs for programming language communities not officially supported by AWS, using the Smithy toolchain.
- Generate API implementations: Create server stubs for language-specific frameworks, including support for Model Context Protocol (MCP) server configurations for AI agents, complete with built-in validation.
- Build custom developer tools: Develop mock testing tools, IAM policy generators, or higher-level abstractions for AWS integration.
- Understand AWS API behaviors: Gain concise and easy insight into how AWS SDKs interpret API calls and their expected behaviors.
David Wells, a full-stack developer, tweeted on X:
This is an incredible 1st-party repo containing all AWS service models. An example use case: Drop a Smithy definition of service [xyz] into Google AI Studio and ask it questions about the service and its operations. I’m finding hidden gems I never knew existed.
The api-models-aws GitHub repository hosts these Smithy models in JSON Abstract Syntax Tree (AST) format, where each model defines service types, operations (including input, output, traits, and errors), and references to specific targets, like the RunInstances API in Amazon EC2. Smithy’s “shapes” represent types, while “traits” add crucial metadata for clients, servers, or documentation, providing detailed API information such as usage examples.
Developers can leverage Smithy build tools like the Smithy CLI to work with these models, perform ad-hoc validation, compare models, and generate code without requiring a Java setup. AWS provides sample projects, including templates for building a minimal Amazon DynamoDB SDK client using Smithy TypeScript, as well as examples for building MCP servers that model tools as Smithy APIs or proxy MCP servers for any Smithy service.
Lastly, more information is available on the Smithy.io website, including its code generation guide.
