Skip to content
NSmithy

Introduction

Smithy is an interface definition language (IDL) developed by AWS for describing services. A Smithy model defines an API’s operations, input and output shapes, errors, and traits. Tooling can then use that model to generate clients, servers, documentation, and protocol-specific bindings. Smithy is used for AWS public APIs and has generators for Java, Kotlin, TypeScript, Python, Rust, Swift, Go, Scala, Ruby, and now C#.

Why Smithy?

Section titled “Why Smithy?”
  • Contract-first. The Smithy model is the API contract: operations, input and output shapes, errors, and documentation live in one place. Because it is model files, the contract can be published, versioned, and shared between teams without shipping generated code.
  • Protocol agnostic. The service definition is separate from the wire protocol. The same model can be exposed over REST, JSON-RPC, gRPC, RPC v2 CBOR, or another protocol supported by your tooling.
  • Works across ecosystems. Smithy is not tied to one runtime or language. A .NET service generated by NSmithy can speak the same protocol as clients generated for Java, TypeScript, Python, Go, Rust, and other ecosystems.
  • Trait system. HTTP bindings, auth, pagination, retries, validation, and documentation are represented as traits on the model, so important API behavior stays close to the shapes and operations it describes.

What NSmithy Does

Section titled “What NSmithy Does”

NSmithy brings Smithy code generation into .NET projects. It integrates with MSBuild, so dotnet build also runs Smithy codegen. From your .smithy model files it generates:

  • C# records for all shapes (structures, unions, enums).
  • Typed async client interfaces and implementations per service.
  • ASP.NET Core minimal API handler interfaces and routing adapters per service.

Many Smithy projects use Gradle to run code generation. NSmithy packages the generator with the MSBuild integration instead, so application projects do not need Gradle and can stay in the .NET build system.

NSmithy currently supports alloy#simpleRestJson, aws.protocols#restJson1, aws.protocols#awsJson1_1, aws.protocols#awsJson1_0, aws.protocols#restXml, smithy.protocols#rpcv2Cbor, and alloy#grpc.

See the Quick Start to build your first service.