# TypeSpec — Define APIs with Types by Microsoft

> TypeSpec is an API definition language by Microsoft that lets you describe REST, OpenAPI, gRPC, and other API protocols using a concise, type-safe syntax. It generates OpenAPI specs, client SDKs, and server stubs from a single source of truth.

## Install

Save in your project root:

# TypeSpec — Define APIs with Types by Microsoft

## Quick Use
```bash
npm install -g @typespec/compiler
tsp init
tsp compile .
# Generates OpenAPI spec from your TypeSpec definitions
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-6080f271
Author: AI Open Source