-1
Daily
5,947
stars
424
forks
44
watchers
7,395
prs
4,959
issues
620
releases
README
TypeSpec
Official Docs | Try TypeSpec Online | Getting Started | Language Overview
TypeSpec is a language for defining cloud service APIs and shapes. TypeSpec is a highly extensible language with primitives that can describe API shapes common among REST, OpenAPI, gRPC, and other protocols.
TypeSpec is excellent for generating many different API description formats, client and service code, documentation, and other assets while keeping your TypeSpec definition as a single source of truth.
Using TypeSpec, you can create reusable patterns for all aspects of an API and package those reusable patterns into libraries. These patterns establish "guardrails" for API designers and make it easier to follow best practices than to deviate from them. TypeSpec also has a rich linter framework with the ability to flag anti-patterns as well as an emitter framework that lets you control the output to ensure it follows the patterns you want.
TypeSpec is a Microsoft-built, community-supported project. Your ideas, feedbacks, and code make all the difference and we deeply appreciate the support from the community.
Installation
npm install -g @typespec/compiler
Tools
The TypeSpec VS Code extension can be installed from the VS Code marketplace or directly on the command line:
tsp code install
The TypeSpec VS Extension can be installed from the VS Marketplace or directly on the command line:
tsp vs install
Usage
TypeSpec to OpenAPI 3.0 Example
This example uses the @typespec/http, @typespec/rest, and @typespec/openapi3 libraries to define a basic REST service and generate an OpenAPI 3.0 document from it.
Run the following command and select "Generic REST API":
tsp init
Hit enter a few times to confirm the defaults.
Copy the contents below into your main.tsp:
typespec
import "@typespec/http";
import "@typespec/rest";
import "@typespec/openapi3";
using Http;
using Rest;
/ This is a pet store service. /
@service({ title: "Pet Store Service" })
@server("https://example.com", "The service endpoint")
namespace PetStore;
@route("/pets")
interface Pets {
list(): Pet[];
}
model Pet {
@minLength(100)
name: string;
@minValue(0)
@maxValue(100)
age: int32;
kind: "dog" | "cat" | "fish";
}
Install the dependencies of main.tsp:
tsp install
Compile it to OpenAPI 3.0:
tsp compile main.tsp --emit @typespec/openapi3
You can find the emitted OpenAPI output in ./tsp-output/openapi.json.
Advanced Scenarios
Installing nightly version
On every commit to the main branch, packages with changes are automatically published to npm with the @next tag.
The packages section shows which version corresponds to the next tag for each package.
To use a nightly version of the packages, go over each one of the packages in the package.json file and update it to either the latest published @next version or @latest, whichever is the newest. You can also use the tag latest or next instead of an explicit version.
After updating the package.json fiTop issues
#2463POC TypeSpec to AsyncAPI33 comments · 2023-09-21#12454[http-client-csharp] Replace general Roslyn simplification with bounded provider-driven reduction20 comments · 2026-10-31#4903.NET Client Patterns: Simple service description should generate client following unbranded .NET client patterns20 comments · 2024-10-29#826Invalid OA3 for unions19 comments · 2022-08-08#2819Have an explicit way of defining the api version parameter17 comments · 2024-01-24#3314Type of model property/enum member when it is defined as constant number14 comments · 2024-05-10#2459OpenAPI and JSON Schema don't support tuple declarations14 comments · 2023-09-21#5419[Bug]: When main.tsp only contain minimal import, emitter fails11 comments · 2024-12-20
Discussions
#12553Should linter diagnostics for library-defined query parameters appear at their usage site?0 comments · 2026-11-12#12451"Model name must be alphanumeric" with namespaced models1 comments · 2026-10-31#11868[@typespec/http-server-csharp] 1.15.0 : generated Program.cs is a MVC one not a WebAPI?2 comments · 2026-09-06#11634Able to perform routine task in decorator?1 comments · 2026-08-12#11037Help with @friendlyName1 comments · 2026-06-22#11034FilterVisibility2 comments · 2026-06-22#10304CodeGen based on OpenApi/Swagger Spec1 comments · 2026-04-08#9866OpenAPI spec generated for union type with discriminator, generate default value instead of enum to allow using openapi-generator-maven-plugin2 comments · 2026-03-02
Latest release
[email protected] [email protected] 2026-11-11@typespec/compiler Deprecations - 11980 getDiscriminatedUnionFromInheritance(type, discriminator) is deprecated. Pass the program as the first argument so enum member discriminator values use their @encodedName. ts const [union, diagnostics] = getDiscriminatedUnionFromInheritance(program, type, discriminator); Features - 12095 Inspect inline suppressions and local linter disables without compiling a project. Inline results include declaration context and source locations; config results include rule-key locations and diagnostics. For compiled programs, inspect whether each pro