What is Smithy?

Smithy is an interface definition language (IDL) — a way to describe the shape of a service and its data once, in plain text, independent of any programming language or wire protocol.

You write .smithy files describing shapes (your data) and services (your operations). A toolchain then assembles that model and feeds it to code generators, which produce clients, servers, type definitions, and docs in many languages — all from the single model.

Model-first and protocol-agnostic

The model never hard-codes how bytes travel. Whether your API speaks REST over JSON, an RPC protocol, or something else is layered on later via traits (annotations like @http). The same model can target several protocols — that’s what protocol-agnostic means.

$version: "2.0"

namespace example

/// A friendly greeting.
string Greeting

That’s a complete, valid model. It has the three things every model needs:

• a $version control statement (always the first line),
• a namespace — a dotted prefix that scopes the names you define, and
• at least one shape (here, a named string called Greeting).

Note the /// comment above Greeting: triple-slash comments become real documentation in the model. Plain // comments are ignored.

Your turn

The editor below talks to the real Smithy compiler. Write your model, hit Check, and you’ll see the same diagnostics the assembler produces.