Smithy#
Smithy is a language for defining services and SDKs.
$version: "2"
namespace example.weather
service Weather {
version: "2006-03-01"
resources: [City]
operations: [GetCurrentTime]
}
resource City {
identifiers: { cityId: CityId }
read: GetCity
list: ListCities
resources: [Forecast]
}
Next steps
- Find out more about Smithy models and this example in the Quick start.
- Find the source code on Github.
Features#
|
|
FAQ#
Why did you develop Smithy?#
Smithy is based on an interface definition language that has been widely used within Amazon and AWS for over a decade. We decided to release Smithy publicly to let other developers use Smithy for their own services and benefit from our years of experience with building tens of thousands of services. By releasing the Smithy specification and tooling, we also hope to make it easier for developers to maintain open source AWS SDKs.
Does Smithy only work with AWS?#
No. Smithy can be used with any kind of service. All AWS-specific metadata in Smithy is implemented as decoupled packages.
Why not just use an existing IDL?#
At AWS, we rely heavily on metadata, code generation, service frameworks, client libraries, and automated policy enforcement. Existing IDLs available outside of AWS were not extensible enough to meet our needs and not compatible with our existing services.
How is Smithy different than other IDLs and frameworks?#
- Smithy is built for code generation and tools. Smithy models were designed for the purpose of generating code for multiple programming languages. For example, Smithy models are completely normalized, which gives all generated types an explicit name and makes models easy to traverse, validate, and diff.
- Smithy can be extended and constrained. Traits are used to extend a model and add capabilities that are not part of the core specification. For example, AWS defines AWS-specific traits that are used to generate other metadata documents that are derived from Smithy models. While extensibility is a key design requirement, Smithy provides a built-in validation system that ensures models adhere to a configurable set of rules and policies.
- Smithy is protocol agnostic. Smithy decouples the transport layer of web services from the data structures and capabilities of the service so that they can evolve independently.
- Smithy helps large organizations collaborate on APIs. Smithy allows different aspects of a model to be owned by different teams. We use this feature at AWS to allow the documentation teams to own API documentation, while service owners control the shape and operations of a service.
- Smithy models can be altered for different audiences. Smithy's projection system allows the contents of a model to be filtered and changed based on who a particular build of a model is intended for. This allows for use cases like maintaining an internal and external version of a model and providing beta models to customers as part of a private beta.
What does protocol-agnostic mean?#
Protocol-agnostic means that the model is an abstraction that specifies the rules and semantics of how a client and server communicate. The transport and serialization format of a service is left as an implementation detail, allowing them to evolve over time. For example, a service owner may wish to evolve their serialization format (e.g., move from text to binary), their connection type (e.g., move from HTTP/1 to HTTP/2), or launch entirely new capabilities.
What is the main difference between Smithy and OpenAPI?#
The primary difference between Smithy and OpenAPI is that Smithy is protocol-agnostic, allowing Smithy to describe a broader range of services, metadata, and capabilities. Smithy can be used alongside OpenAPI by converting Smithy models to OpenAPI.