TypeSpec

TypeSpec is a modern, high-level API definition language designed for API-centric development. It allows you to describe APIs using a concise, familiar syntax (inspired by TypeScript and C#) and then compile those descriptions into various industry-standard formats such as OpenAPI, JSON Schema, or Protobuf—often simultaneously.

Key capabilities include:

• Abstraction: Encapsulate common data types, API patterns, and guidelines into reusable components.
• Interoperability: Output multiple protocols, clients, servers, and documentation from a single source of truth.
• Extensibility: Extend the language with custom decorator vocabularies and type templates to model business-specific logic.
• Ecosystem: Package common types, linters, and emitters as NPM packages for distribution within organizations or the wider community.

The Mutator Framework is an experimental utility for building mutations of the TypeSpec type graph. Mutations create a parallel type graph that contains modifications to the original graph and additional metadata relevant to consumers.

To use the framework, you typically:

1. Create mutation classes to control how TypeSpec types (models, properties, unions, etc.) are traversed and transformed.
2. Use helper APIs on mutation nodes to mutate types or traverse to related nodes.
3. Instantiate a MutationEngine (such as SimpleMutationEngine) using the Typekit from your TypeSpec program.

@typespec/tspd is an experimental tool designed to assist in building TypeSpec libraries and emitters. It provides functionality to:

• Generate decorator signatures and type checks.
• Generate documentation for library types and emitter options.

Warning: This library is experimental and its API is subject to significant changes in future versions.

# Example usage for generating external signatures
tspd --enable-experimental gen-extern-signature

# Example usage for generating documentation for the current directory
tspd --enable-experimental doc . --output-dir ./docs/

TypeSpec 1.0 is generally available and includes several production-ready components for API modeling and generation. Use these stable packages for production environments:

Compiler and Core Libraries

• @typespec/compiler: The core TypeSpec language compiler.
• @typespec/http: Support for the HTTP protocol.
• @typespec/openapi: Support for OpenAPI definitions.

IDE Support

• typespec-vscode: The official VS Code extension for TypeSpec development.

Stable Emitters

• @typespec/openapi3: Generates OpenAPI 3.0 specifications.
• @typespec/json-schema: Generates JSON Schema outputs.

The TypeSpec Visual Studio extension provides comprehensive language support for TypeSpec files within the Visual Studio IDE.

Key features include:

• Live diagnostic reporting: Real-time feedback on syntax and errors.
• IntelliSense: Syntax highlighting, code completion, and hover information.
• Navigation & Refactoring: Go to definition and rename refactoring.
• Editor Utilities: Code folding and formatting.

The @typespec/streams library provides bindings for stream-based operations in TypeSpec. It includes the following core components:

Decorators

• @streamOf: Used to define stream-based properties or types.

Models

• Stream: A data type representing a stream.

The @typespec/http-client-csharp library is a TypeSpec library designed to emit HTTP Client libraries for C#. It works in conjunction with TypeSpec.HttpClient to transform TypeSpec definitions into functional C# client code.

For detailed instructions on configuring the emitter and using generator plugins, refer to the specific documentation pages for Emitter usage and Generator plugins.