Skip to main content
Version: Next 🚧

Language Overview

This document provides a concise overview of the language concepts in TypeSpec. It serves as a quick reference guide rather than an in-depth tutorial.

Declarations

  • Names of declarations must be unique across different types within the same scope. For instance, the following is not permissible:
    model Dog {}
    namespace Dog {}

Imports

For more details, see: Imports

FeatureExample
Import TypeSpec fileimport "./models.tsp"
Import JS fileimport "./models.js"
Import Libraryimport "@typespec/rest"

Namespaces

For more details, see: Namespaces

FeatureExample
Declare namespacenamespace PetStore {}
File namespacenamespace PetStore;
Nested namespacenamespace PetStore.Models;
Using namespaceusing PetStore.Models;

Decorators

For more details, see: Decorators

FeatureExample
Use decorator@mark
Use decorator with arguments@tag("abc")
Declare a decorator in JSexport function $tag(context: DecoratorContext, target: Type, name: string) {...}
Save state in decoratorcontext.program.stateMap(key).set(target, <value>)
Augment decorator@@tag(MyType, "abc");

Scalars

For more details, see: Scalars

FeatureExample
Scalar declarationscalar ternary
Extend scalarscalar Password extends string
Template scalar@doc(T) scalar Password<T extends string>

Models

For more details, see: Models

FeatureExample
Model declarationmodel Pet {}
Model inheritancemodel Dog extends Pet {}
scalar ismodel uuid extends string;
Model spreadmodel Dog {...Animal}
Propertymodel Dog { name: string }
Optional propertymodel Dog { owner?: string }
Optional property with defaultmodel Dog { name?: string = "Rex" }
Model templatemodel Pet<T> { t: T }

Operations

For more details, see: Operations

FeatureExample
Operation declarationop ping(): void
Operation with parametersop upload(filename: string, data: bytes): void
Operation with return typeop health(): HealthStatus
Operation with multiple typesop health(): HealthStatus | ErrorResponse
Operation templateop getter<T>(id: string): T
Operation isop getPet is getter<Pet>;

Interfaces

For more details, see: Interfaces

FeatureExample
Interface declarationinterface PetStore { list(): Pet[] }
Interface compositioninterface PetStore extends Store { }
Interface templateinterface Restful<T> { list(): T[] }

Templates

For more details, see: Templates

FeatureExample
Simple templatemodel Response<T> {value: T}
Template with multiple parametersmodel Response<K, V> {key: K, value: T}
Template defaultmodel Response<T = string> {value: T}
Template constraintsmodel Response<T extends {id: string}> {value: T}
Template constraints and defaultsmodel Response<T extends string = ""> {value: T}

Enums

For more details, see: Enums

FeatureExample
Enum declarationenum Direction {Up, Down}
Enum string valuesenum Direction {Up: "up", Down: "down"}
Enum int valuesenum Size {Small: 1000, Large: 2000}
Enum float valuesenum Part {Quarter: 0.25, Half: 0.5}
Enum composingenum Direction2D {...Direction, Left, Right}

Unions

For more details, see: Unions

FeatureExample
Union declaration"cat" | "dog"
Named union declarationunion Pet {cat: Cat, dog: Dog}

Intersections

For more details, see: Intersections

FeatureExample
Intersection declarationPet & Animal

Type literals

For more details, see: Type literals

FeatureExample
String"Hello world!"
Multi line String"""\nHello world!\n""" (\n) represent actual new lines
Int10
Float10.0
Booleanfalse

Aliases

For more details, see: Aliases

FeatureExample
Alias declarationalias Options = "one" | "two";