Modern software is built from networks of connected services. Each service exposes APIs — the contracts that define how systems communicate. To describe those contracts, developers rely on Interface Definition Languages (IDLs). An IDL isn’t just a format for documentation; it’s a way to design and formalize how software components interact before any code is written. In essence, it lets us design the interface first — and code second.

This philosophy is at the heart of Spec-driven or Model-first development. Instead of implementing features and documenting them later, teams define a single model of the system, and from it generate the code, SDKs, documentation, and even test scaffolds. It’s a reflection of a customer-first mindset: starting from how users experience the service, not how it’s implemented. The model becomes a single source of truth for every team involved.

OpenAPI has long served as the foundation for this approach. It provides a standardized way to describe RESTful APIs and has evolved into a powerful ecosystem with tools like OpenAPI Generator and Swagger Codegen. With these, developers can automatically create client SDKs, server stubs, and interactive documentation from a single spec. OpenAPI has effectively become the common language of HTTP-based APIs.

That said, OpenAPI still operates primarily as a file-based specification. As systems scale, specs often need to be split across multiple YAML files, each connected through $ref paths like ./schemas/user.yaml. While this approach works, it can feel rigid and fragile — dependent on file structures rather than logical relationships. The syntax itself is descriptive but not inherently expressive, making it harder to model complex abstractions or reuse types across domains.

Smithy, developed by AWS, takes a different approach. It treats API definitions as language-level models rather than documents. Each structure is defined as a shape, and instead of path-based references, Smithy uses namespaces — so types are referenced semantically, like example.weather#Temperature. This small difference makes a big impact: it allows teams to manage APIs modularly, reuse types easily, and evolve large service models with the same flexibility as code.

Because Smithy models are independent of protocol, AWS uses them to generate not only OpenAPI specs, but also SDKs, validators, test simulators, and event stream definitions — all from one source. It’s an elegant solution to a real engineering challenge: maintaining consistent interfaces across multiple surfaces like HTTP APIs, CLIs, SDKs, and internal service contracts. That same flexibility suggests Smithy could have applications far beyond AWS’s ecosystem.

OpenAPI will continue to play an essential role in the public API landscape, but Smithy shows how a modeling language can unify different interfaces within a single organization. AWS built it out of necessity — to manage scale and complexity — yet its underlying idea is universal. In a world where every product exposes multiple ways to connect, a shared modeling language like Smithy could become a powerful foundation for how we think about interfaces themselves.