Smithy, an extensible API definition language

Smithy is a protocol-agnostic interface definition language and set of tools for building clients, servers, and documentation for any programming language.
Get started Specifications
[full example]namespace example.weather

service Weather {
  version: "2006-03-01",
  resources: [City],
  operations: [GetCurrentTime]
}

resource City {
  identifiers: { cityId: CityId },
  read: GetCity,
  list: ListCities,
  resources: [Forecast],
}

Protocol-agnostic

Smithy is designed to work with any programming language, describe services running in any environment, and work with any kind of transport or serialization format.

Extensible

Smithy models can be extended through traits. There are many built-in traits to affect things like behavior and serialization, and custom traits can be added for additional functionality.

Enforce standards & consistency

Customizable standards and validation constraints ensure that APIs adhere to any kind of standard or convention. Rule sets can be shared and applied to all APIs in an organization.

Resource based

Smithy is defined in terms of resources and operations you can enact on them. Explicitly defining resources provides rich metadata about an API that can be used to build higher-level client tooling and derive artifacts from a model.

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. In fact, all AWS-specific metadata in Smithy is loaded using additional 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 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.

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.

Site map