TypeSpec — Define APIs with Types by Microsoft

Introduction

TypeSpec is a language purpose-built for describing APIs. Created by Microsoft and used internally for Azure services, it provides a concise, composable syntax for defining data models, operations, and protocols that compiles down to OpenAPI, JSON Schema, Protobuf, and other output formats.

What TypeSpec Does

• Defines API shapes using a TypeScript-like type syntax with decorators for metadata
• Compiles to OpenAPI 3.0/3.1, JSON Schema, Protobuf, and other output formats via emitters
• Supports REST, gRPC, and custom protocol patterns through composable libraries
• Generates client SDKs and server stubs from a single API definition
• Validates API designs against style guides and governance rules at compile time

Architecture Overview

TypeSpec uses a compiler written in TypeScript that parses .tsp files into an intermediate type graph. Emitters then walk this graph to produce output in target formats. The language supports namespaces, templates, and union types for modeling complex APIs. Decorators like @route, @query, and @body annotate operations with protocol-specific metadata. Libraries extend the core language with domain-specific patterns, and the compiler supports a plugin system for custom validation and generation.

Self-Hosting & Configuration

• Install the compiler globally with npm install -g @typespec/compiler or use npx
• Initialize a new project with tsp init which scaffolds a tspconfig.yaml and main.tsp file
• Configure emitters in tspconfig.yaml to target OpenAPI, Protobuf, or custom outputs
• Use the VS Code extension for syntax highlighting, completions, and inline diagnostics
• Add @typespec/http and @typespec/rest libraries for REST API definitions with standard patterns

Key Features

• TypeScript-inspired syntax that is familiar to web developers
• Composable libraries for HTTP, REST, OpenAPI, Protobuf, and versioning patterns
• Template types and model inheritance for reusable API shapes
• Compile-time validation and linting for API design consistency
• IDE support with VS Code extension providing completions, diagnostics, and go-to-definition

Comparison with Similar Tools

• OpenAPI (YAML/JSON) — raw spec format; TypeSpec offers a more concise authoring experience that compiles to OpenAPI
• Protobuf — binary protocol definition; TypeSpec can target Protobuf as one of several output formats
• Smithy — AWS API definition language; TypeSpec is protocol-agnostic and more TypeScript-aligned
• GraphQL SDL — schema language for GraphQL APIs; TypeSpec covers REST, gRPC, and other protocols
• Buf — Protobuf toolchain; TypeSpec is broader, covering REST and OpenAPI alongside Protobuf

FAQ

Q: Is TypeSpec only for Azure APIs? A: No. TypeSpec is a general-purpose API definition language. While Microsoft uses it for Azure, it works for any REST, gRPC, or custom API project.

Q: Can I use TypeSpec with existing OpenAPI specs? A: Yes. TypeSpec can import existing OpenAPI documents and you can incrementally adopt it alongside hand-written specs.

Q: Does TypeSpec support API versioning? A: Yes. The @typespec/versioning library provides decorators for defining version-aware APIs with added, removed, and renamed fields across versions.

Q: How does TypeSpec compare to writing OpenAPI YAML directly? A: TypeSpec is more concise, supports inheritance and templates for reuse, and catches errors at compile time rather than at validation time.

Sources

• https://github.com/microsoft/typespec
• https://typespec.io