Built-in Data types

TypeSpec

Array

model Array<Element>

Template Parameters

Name	Description
Element	The type of the array elements

Properties

None

Create

A copy of the input model T with only the properties that are visible during the “Create” resource lifecycle phase.

This transformation is recursive, and will include only properties that have the Lifecycle.Create visibility modifier.

If a NameTemplate is provided, the new model will be named according to the template. The template uses the same syntax as the @friendlyName decorator.

model Create<T, NameTemplate>

Template Parameters

Name	Description
T	The model to transform.
NameTemplate	The name template to use for the new model. *

Examples

model Dog {
  @visibility(Lifecycle.Read)
  id: int32;

  name: string;
}

model CreateDog is Create<Dog>;

Properties

None

CreateOrUpdate

A copy of the input model T with only the properties that are visible during the “Create” or “Update” resource lifecycle phases.

This transformation is recursive, and will include only properties that have the Lifecycle.Create or Lifecycle.Update visibility modifier.

If a NameTemplate is provided, the new model will be named according to the template. The template uses the same syntax as the @friendlyName decorator.

model CreateOrUpdate<T, NameTemplate>

Template Parameters

Name	Description
T	The model to transform.
NameTemplate	The name template to use for the new model. *

Examples

model Dog {
  @visibility(Lifecycle.Read)
  id: int32;

  name: string;
}

model CreateOrUpdateDog is CreateOrUpdate<Dog>;

Properties

None

DefaultKeyVisibility

Applies a visibility setting to a collection of properties.

model DefaultKeyVisibility<Source, Visibility>

Template Parameters

Name	Description
Source	An object whose properties are spread.
Visibility	The visibility to apply to all properties.

Properties

None

ExampleOptions

Options for example decorators

model ExampleOptions

Properties

Name	Type	Description
title?	string	The title of the example
description?	string	Description of the example

object

Caution

Deprecated: object is deprecated. Please use {} for an empty model, Record<unknown> for a record with unknown property types, unknown[] for an array.

Represent a model

model object

Properties

None

OmitDefaults

Represents a collection of properties with default values omitted.

model OmitDefaults<Source>

Template Parameters

Name	Description
Source	An object whose spread property defaults are all omitted.

Properties

None

OmitProperties

Represents a collection of omitted properties.

model OmitProperties<Source, Keys>

Template Parameters

Name	Description
Source	An object whose properties are spread.
Keys	The property keys to omit.

Properties

None

OperationExample

Operation example configuration.

model OperationExample

Properties

Name	Type	Description
parameters?	unknown	Example request body.
returnType?	unknown	Example response body.

OptionalProperties

Represents a collection of optional properties.

model OptionalProperties<Source>

Template Parameters

Name	Description
Source	An object whose spread properties are all optional.

Properties

None

PickProperties

Represents a collection of properties with only the specified keys included.

model PickProperties<Source, Keys>

Template Parameters

Name	Description
Source	An object whose properties are spread.
Keys	The property keys to include.

Properties

None

Read

A copy of the input model T with only the properties that are visible during the “Read” resource lifecycle phase.

This transformation is recursive, and will include only properties that have the Lifecycle.Read visibility modifier.

If a NameTemplate is provided, the new model will be named according to the template. The template uses the same syntax as the @friendlyName decorator.

model Read<T, NameTemplate>

Template Parameters

Name	Description
T	The model to transform.
NameTemplate	The name template to use for the new model. *

Examples

model Dog {
  @visibility(Lifecycle.Read)
  id: int32;

  name: string;
}

model ReadDog is Read<Dog>;

Properties

None

Record

model Record<Element>

Template Parameters

Name	Description
Element	The type of the properties

Properties

None

ServiceOptions

Service options.

model ServiceOptions

Properties

Name	Type	Description
title?	string	Title of the service.
version?	string	Version of the service.

Update

A copy of the input model T with only the properties that are visible during the “Update” resource lifecycle phase.

This transformation will include only the properties that have the Lifecycle.Update visibility modifier, and the types of all properties will be replaced with the equivalent CreateOrUpdate transformation.

If a NameTemplate is provided, the new model will be named according to the template. The template uses the same syntax as the @friendlyName decorator.

model Update<T, NameTemplate>

Template Parameters

Name	Description
T	The model to transform.
NameTemplate	The name template to use for the new model. *

Examples

model Dog {
  @visibility(Lifecycle.Read)
  id: int32;

  name: string;
}

model UpdateDog is Update<Dog>;

Properties

None

UpdateableProperties

Represents a collection of updateable properties.

model UpdateableProperties<Source>

Template Parameters

Name	Description
Source	An object whose spread properties are all updateable.

Properties

None

VisibilityFilter

A visibility filter, used to specify which properties should be included when using the withVisibilityFilter decorator.

The filter matches any property with ALL of the following:

• If the any key is present, the property must have at least one of the specified visibilities.
• If the all key is present, the property must have all of the specified visibilities.
• If the none key is present, the property must have none of the specified visibilities.

model VisibilityFilter

Properties

Name	Type	Description
any?	EnumMember[]
all?	EnumMember[]
none?	EnumMember[]

ArrayEncoding

Encoding for serializing arrays

enum ArrayEncoding

Name	Value	Description
pipeDelimited		Each values of the array is separated by a |
spaceDelimited		Each values of the array is separated by a

BytesKnownEncoding

Known encoding to use on bytes

enum BytesKnownEncoding

Name	Value	Description
base64	"base64"	Encode to Base64
base64url	"base64url"	Encode to Base64 Url

DateTimeKnownEncoding

Known encoding to use on utcDateTime or offsetDateTime

enum DateTimeKnownEncoding

Name	Value	Description
rfc3339	"rfc3339"	RFC 3339 standard. https://www.ietf.org/rfc/rfc3339.txt Encode to string.
rfc7231	"rfc7231"	RFC 7231 standard. https://www.ietf.org/rfc/rfc7231.txt Encode to string.
unixTimestamp	"unixTimestamp"	Encode a datetime to a unix timestamp. Unix timestamps are represented as an integer number of seconds since the Unix epoch and usually encoded as an int32.

DurationKnownEncoding

Known encoding to use on duration

enum DurationKnownEncoding

Name	Value	Description
ISO8601	"ISO8601"	ISO8601 duration
seconds	"seconds"	Encode to integer or float

Lifecycle

A visibility class for resource lifecycle phases.

These visibilities control whether a property is visible during the create, read, and update phases of a resource’s lifecycle.

enum Lifecycle

Name	Value	Description
Create
Read
Update

Examples

model Dog {
 @visibility(Lifecycle.Read) id: int32;
 @visibility(Lifecycle.Create, Lifecycle.Update) secretName: string;
 name: string;
}

In this example, the id property is only visible during the read phase, and the secretName property is only visible during the create and update phases. This means that the server will return the id property when returning a Dog, but the client will not be able to set or update it. In contrast, the secretName property can be set when creating or updating a Dog, but the server will never return it. The name property has no visibility modifiers and is therefore visible in all phases.

boolean

Boolean with true and false values.

scalar boolean

bytes

Represent a byte array

scalar bytes

decimal

A decimal number with any length and precision. This represent any decimal value possible. It is commonly represented as BigDecimal in some languages.

scalar decimal

decimal128

A 128-bit decimal number.

scalar decimal128

duration

A duration/time period. e.g 5s, 10h

scalar duration

float

A number with decimal value

scalar float

float32

A 32 bit floating point number. (±1.5 x 10^−45 to ±3.4 x 10^38)

scalar float32

float64

A 64 bit floating point number. (±5.0 × 10^−324 to ±1.7 × 10^308)

scalar float64

int16

A 16-bit integer. (-32,768 to 32,767)

scalar int16

int32

A 32-bit integer. (-2,147,483,648 to 2,147,483,647)

scalar int32

int64

A 64-bit integer. (-9,223,372,036,854,775,808 to 9,223,372,036,854,775,807)

scalar int64

int8

A 8-bit integer. (-128 to 127)

scalar int8

integer

A whole number. This represent any integer value possible. It is commonly represented as BigInteger in some languages.

scalar integer

numeric

A numeric type

scalar numeric

offsetDateTime

A date and time in a particular time zone, e.g. “April 10th at 3:00am in PST”

scalar offsetDateTime

plainDate

A date on a calendar without a time zone, e.g. “April 10th”

scalar plainDate

plainTime

A time on a clock without a time zone, e.g. “3:00 am”

scalar plainTime

safeint

An integer that can be serialized to JSON (−9007199254740991 (−(2^53 − 1)) to 9007199254740991 (2^53 − 1) )

scalar safeint

string

A sequence of textual characters.

scalar string

uint16

A 16-bit unsigned integer (0 to 65,535)

scalar uint16

uint32

A 32-bit unsigned integer (0 to 4,294,967,295)

scalar uint32

uint64

A 64-bit unsigned integer (0 to 18,446,744,073,709,551,615)

scalar uint64

uint8

A 8-bit unsigned integer (0 to 255)

scalar uint8

unixTimestamp32

Represent a 32-bit unix timestamp datetime with 1s of granularity. It measures time by the number of seconds that have elapsed since 00:00:00 UTC on 1 January 1970.

scalar unixTimestamp32

url

Represent a URL string as described by https://url.spec.whatwg.org/

scalar url

utcDateTime

An instant in coordinated universal time (UTC)”

scalar utcDateTime