Loading comparison...
Loading comparison...
Microsoft's language for defining API contracts. Generates OpenAPI specs, client libraries, and server stubs.
Microsoft developed TypeSpec (originally called Cadl) and open-sourced it in 2022 as a language purpose-built for defining API contracts and generating multiple output artifacts from a single source of truth. TypeSpec addresses the growing complexity of maintaining API specifications by providing a concise, typed, and composable syntax for describing REST, gRPC, and other API styles that compiles to OpenAPI 3.0/3.1, JSON Schema, Protobuf, and client library code. The language draws syntactic inspiration from TypeScript, making it immediately approachable for web developers, while adding API-specific constructs like decorators (@route, @query, @body), model composition, template types, and versioning primitives.
TypeSpec is used internally at Microsoft for defining Azure service APIs, ensuring consistency across hundreds of services and automatically generating SDKs for Python, JavaScript, Java, .NET, and Go. The language's decorator system is extensible — teams can create custom decorators that enforce organizational API standards, generate documentation, or produce specialized output formats. TypeSpec supports namespaces for organizing large API definitions, interfaces for grouping operations, and union types for polymorphic responses.
The tooling includes a VS Code extension with IntelliSense, a formatter, a linter, and a playground for experimentation. The compiler's emitter architecture allows plugging in custom code generators for any target format. By centralizing API definitions in TypeSpec rather than maintaining separate OpenAPI YAML files, client SDKs, and server stubs, teams eliminate drift between specification and implementation — a persistent problem in API-first development.
TypeSpec changes propagate to every downstream artifact — OpenAPI specs, client SDKs, server stubs, and documentation — making each modification high-impact. Comparing TypeSpec files catches modified model properties that break client serialization, altered route decorators that change endpoint URLs, changed versioning annotations that affect API compatibility, and updated interface definitions that modify the operation contract.
API designers need precise diffs to verify that specification changes are intentional and backward-compatible before triggering regeneration of all downstream artifacts.
UtraDiff opens TypeSpec API definition files in a diff editor with TypeSpec syntax highlighting, coloring decorators, model definitions, and operation signatures. Side-by-side and inline views expose changes to API contracts, response schemas, and versioning decorators.
The whitespace-ignore toggle filters formatting noise from auto-generated specs. Keyboard navigation jumps between changed regions so teams can verify that API surface changes are intentional before regenerating OpenAPI output.
Supported extensions: .tsp