Skip to content

What is TypeSpec?

TypeSpec (Compact API Definition Language) is a typescript-like language for defining APIs. TypeSpec is designed for code reuse, and for Azure services, there are Azure service extensions for TypeSpec that provide high level building blocks you should use to build your service. These libraries also contain rules that encourage following established patterns for Azure APIs. Using these building blocks and guard rails, your service API will be easier to build, will have an easier time passing API reviews, will be consistent with other Azure services, and will produce good API documentation, good SDKs, and good CLIs. TypeSpec can emit the following artifacts for your service:

  • OpenAPI3 specs
  • OpenAPI2 specs, suitable for check-in in to the azure-rest-api-specs repo

For more information on the TypeSpec language and core libraries, see Getting started with TypeSpec

Setting up TypeSpec and compile first project

Install TypeSpec

There are two simple options for getting TypeSpec up and running in your environment:

Create a new TypeSpec Azure project

  • Run tsp init command with Azure template URL https://aka.ms/typespec/azure-init to create a new TypeSpec Azure project for ARM or Data-plane service APIs. This will initialize an empty TypeSpec project with correct npm package references and emitter settings for Azure services.

  • Run tsp compile in the project folder will compile the TypeSpec project and emit output in tsp-output folder.

Once TypeSpec project has been create, the TypeSpec language tutorial provides a good overview of the basics of the language.

Getting Started for Azure Management Plane Services

Use the resources in this section for creating Azure ARM rest API specs. For ProviderHub User RP specs and service implementation, please follow the steps in the next section.

Getting Started for Azure Data Plane Services

How to Get Help

Troubleshooting VSCode Tooling and Filing Issues

If you run into a problem with the TypeSpec-specific tooling in VS Code, please try to capture the issue, and include any log information. If IntelliSense, syntax highlighting or other language features don’t appear to be working:

  • Ensure that ‘TypeSpec’ is the selected language format for your document (this should happen automatically if your file uses the .tsp suffix) image
  • Choose Output from the View menu to see the output of the language server (View -> Output) image
  • Capture any output, including stack traces, and include in your github issue. image
  • Restart VS Code to restart the language server

More Information About TypeSpec

Some additional sources: