Introduction

Smithy is a protocol-agnostic interface definition language (IDL) developed by AWS. You describe your API once — operations, input/output shapes, and traits — and tooling generates clients, servers, and documentation for any target language or protocol. It is the IDL behind AWS’s public APIs and has first-class code generators for Java, Kotlin, TypeScript, Python, Rust, Swift, Go, Scala, Ruby, and now C#.

Why Smithy?

• Single source of truth. The model drives everything: generated types, serialization, routing, documentation. Changes to the model propagate everywhere automatically.
• Protocol agnostic. The same service definition can be exposed over REST, JSON-RPC, gRPC, or CBOR — you choose at the protocol trait, not in application code.
• Cross-ecosystem. Smithy clients and servers interoperate across languages. A .NET server generated by NSmithy speaks the same wire format as a Java or TypeScript client generated by the official Smithy toolchain.
• Rich trait system. HTTP bindings, auth, pagination, retries, and more are expressed as first-class traits on the model, not scattered across hand-written glue code.

What NSmithy Does

NSmithy is a .NET implementation of the Smithy toolchain. It integrates with MSBuild so that dotnet build also runs Smithy codegen — no separate build step. From your .smithy model files it generates:

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

No Gradle. Other Smithy ecosystems (Java in particular) typically use Gradle to orchestrate codegen. NSmithy deliberately avoids this: the Smithy CLI is invoked as an MSBuild target, so dotnet build is the only build command you need.

Protocol support includes alloy#simpleRestJson, aws.protocols#restJson1, aws.protocols#restXml, and smithy.protocols#rpcv2Cbor.

See the Quick Start to build your first service.