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
Feature | Example |
---|---|
Import TypeSpec file | import "./models.tsp" |
Import JS file | import "./models.js" |
Import Library | import "@typespec/rest" |
Namespaces
For more details, see: Namespaces
Feature | Example |
---|---|
Declare namespace | namespace PetStore {} |
File namespace | namespace PetStore; |
Nested namespace | namespace PetStore.Models; |
Using namespace | using PetStore.Models; |
Decorators
For more details, see: Decorators
Feature | Example |
---|---|
Use decorator | @mark |
Use decorator with arguments | @tag("abc") |
Declare a decorator in JS | export function $tag(context: DecoratorContext, target: Type, name: string) {...} |
Save state in decorator | context.program.stateMap(key).set(target, <value>) |
Augment decorator | @@tag(MyType, "abc"); |
Scalars
For more details, see: Scalars
Feature | Example |
---|---|
Scalar declaration | scalar ternary |
Extend scalar | scalar Password extends string |
Template scalar | @doc(T) scalar Password<T extends string> |
Models
For more details, see: Models
Feature | Example |
---|---|
Model declaration | model Pet {} |
Model inheritance | model Dog extends Pet {} |
scalar is | model uuid extends string; |
Model spread | model Dog {...Animal} |
Property | model Dog { name: string } |
Optional property | model Dog { owner?: string } |
Optional property with default | model Dog { name?: string = "Rex" } |
Model template | model Pet<T> { t: T } |
Operations
For more details, see: Operations
Feature | Example |
---|---|
Operation declaration | op ping(): void |
Operation with parameters | op upload(filename: string, data: bytes): void |
Operation with return type | op health(): HealthStatus |
Operation with multiple types | op health(): HealthStatus | ErrorResponse |
Operation template | op getter<T>(id: string): T |
Operation is | op getPet is getter<Pet>; |
Interfaces
For more details, see: Interfaces
Feature | Example |
---|---|
Interface declaration | interface PetStore { list(): Pet[] } |
Interface composition | interface PetStore extends Store { } |
Interface template | interface Restful<T> { list(): T[] } |
Templates
For more details, see: Templates
Feature | Example |
---|---|
Simple template | model Response<T> {value: T} |
Template with multiple parameters | model Response<K, V> {key: K, value: T} |
Template default | model Response<T = string> {value: T} |
Template constraints | model Response<T extends {id: string}> {value: T} |
Template constraints and defaults | model Response<T extends string = ""> {value: T} |
Enums
For more details, see: Enums
Feature | Example |
---|---|
Enum declaration | enum Direction {Up, Down} |
Enum string values | enum Direction {Up: "up", Down: "down"} |
Enum int values | enum Size {Small: 1000, Large: 2000} |
Enum float values | enum Part {Quarter: 0.25, Half: 0.5} |
Enum composing | enum Direction2D {...Direction, Left, Right} |
Unions
For more details, see: Unions
Feature | Example |
---|---|
Union declaration | "cat" | "dog" |
Named union declaration | union Pet {cat: Cat, dog: Dog} |
Intersections
For more details, see: Intersections
Feature | Example |
---|---|
Intersection declaration | Pet & Animal |
Type literals
For more details, see: Type literals
Feature | Example |
---|---|
String | "Hello world!" |
Multi line String | """\nHello world!\n""" (\n) represent actual new lines |
Int | 10 |
Float | 10.0 |
Boolean | false |
Aliases
For more details, see: Aliases
Feature | Example |
---|---|
Alias declaration | alias Options = "one" | "two"; |