Models

Models in TypeSpec are utilized to define the structure or schema of data.

Types of models

Models can be categorized into two main types:

• Record
• Array

Record

A Record model is a structure that consists of named fields, referred to as properties.

• The name can be an identifier or string literal.
• The type can be any type reference.
• Properties are arranged in a specific order. Refer to property ordering for more details.

model Dog {
  name: string;
  age: number;
}

Optional properties

Properties can be designated as optional by using the ? symbol.

model Dog {
  address?: string;
}

Default values

Optional properties can be assigned a default value using the = operator.

model Dog {
  address?: string = "wild";
}

Property ordering

Properties are arranged in the order they are defined in the source. Properties acquired via model is are placed before properties defined in the model body. Properties obtained via ... are inserted at the point where the spread appears in the source.

Example:

model Pet {
  name: string;
  age: int32;
}

model HasHome {
  address: string;
}

model Cat is Pet {
  meow: boolean;
  ...HasHome;
  furColor: string;
}

// The resulting property order for Cat is:
// name, age, meow, address, furColor

Additional properties

The Record<T> model can be used to define a model with an arbitrary number of properties of type T. It can be combined with a named model to provide some known properties.

There are three ways to achieve this, each with slightly different semantics:

• Using the ... operator
• Using the is operator
• Using the extends operator

Using the ... operator

Spreading a Record into your model implies that your model includes all the properties you have explicitly defined, plus any additional properties defined by the Record. This means that a property in the model could be of a different and incompatible type with the Record value type.

// In this example, the Person model has a property `age` that is an int32, but also has other properties that are all strings.
model Person {
  age: int32;
  ...Record<string>;
}

Using the is operator

When using is Record<T>, it indicates that all properties of this model are of type T. This means that each property explicitly defined in the model must also be of type T.

The example above would be invalid

model Person is Record<string> {
  age: int32;
  //   ^ int32 is not assignable to string
}

But the following would be valid

model Person is Record<string> {
  name: string;
}

Using the extends operator

The extends operator has similar semantics to is, but it defines the relationship between the two models. In many languages, this would probably result in the same emitted code as is and it is recommended to use is Record<T> instead.

model Person extends Record<string> {
  name: string;
}

Special property types

never

A model property can be declared as having the type never. This can be interpreted as the model not having that property.

This can be useful in a model template to omit a property.

model Address<TState> {
  state: TState;
  city: string;
  street: string;
}

model UKAddress is Address<never>;

note

The responsibility of removing never properties lies with the emitter. The TypeSpec compiler will not automatically omit them.

Array

Arrays are models created using the [] syntax, which is a shorthand for using the Array<T> model type.

Model composition

Spread

The spread operator (...) copies the members of a source model into a target model. This operation doesn't create any nominal relationship between the source and target, making it useful when you want to reuse common properties without generating complex inheritance relationships.

model Animal {
  species: string;
}

model Pet {
  name: string;
}

model Dog {
  ...Animal;
  ...Pet;
}

// The Dog model is equivalent to the following declaration:
model Dog {
  species: string;
  name: string;
}

Extends

There are times when you want to create an explicit relationship between two models, such as when you're generating class definitions in languages that support inheritance. The extends keyword can be used to establish this relationship.

model Animal {
  species: string;
}

model Dog extends Animal {}

Is

There are instances when you want to create a new type that is an exact copy of an existing type but with additional properties or metadata, without creating a nominal inheritance relationship. The is keyword can be used for this purpose. It copies all the properties (like spread), but also copies decorators as well. A common use case is to provide a better name to a template instantiation:

@decorator
model Thing<T> {
  property: T;
}

model StringThing is Thing<string>;

// The StringThing declaration is equivalent to the following declaration:
@decorator
model StringThing {
  property: string;
}

Model templates

Refer to templates for more details on templates.

model Page<Item> {
  size: number;
  item: Item[];
}

model DogPage {
  ...Page<Dog>;
}

Meta type references

Some model property meta types can be referenced using ::.

Name	Example	Description
type	Pet.name::type	Reference the type of the model property