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;
}

// This model has only the `name` field.
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.

The “CreateOrUpdate” lifecycle phase is used by default for properties passed as parameters to operations that can create or update data, like HTTP PUT operations.

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;

  @visibility(Lifecycle.Create)
  immutableSecret: string;

  @visibility(Lifecycle.Create, Lifecycle.Update)
  secretName: string;

  name: string;
}

// This model will have the `immutableSecret`, `secretName`, and `name` fields, but not the `id` field.
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

Delete

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

The “Delete” lifecycle phase is used for properties passed as parameters to operations that delete data, like HTTP DELETE operations.

This transformation is recursive, and will include only properties that have the Lifecycle.Delete 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 Delete<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;

  // Set when the Dog is removed from our data store. This happens when the
  // Dog is re-homed to a new owner.
  @visibility(Lifecycle.Delete)
  nextOwner: string;

  name: string;
}

// This model will have the `nextOwner` and `name` fields, but not the `id` field.
model DeleteDog is Delete<Dog>;

Properties

None

DiscriminatedOptions

Options for @discriminated decorator.

model DiscriminatedOptions

Properties

Name	Type	Description
envelope?	"object" | "none"	How is the discriminated union serialized.
discriminatorPropertyName?	string	Name of the discriminator property
envelopePropertyName?	string	Name of the property envelopping the data

ExampleOptions

Options for example decorators

model ExampleOptions

Properties

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

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

Query

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

The “Query” lifecycle phase is used for properties passed as parameters to operations that read data, like HTTP GET or HEAD operations. This should not be confused for the @query decorator, which specifies that the property is transmitted in the query string of an HTTP request.

This transformation is recursive, and will include only properties that have the Lifecycle.Query 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 Query<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;

  // When getting information for a Dog, you can set this field to true to include
  // some extra information about the Dog's pedigree that is normally not returned.
  // Alternatively, you could just use a separate option parameter to get this
  // information.
  @visibility(Lifecycle.Query)
  includePedigree?: boolean;

  name: string;

  // Only included if `includePedigree` is set to true in the request.
  @visibility(Lifecycle.Read)
  pedigree?: string;
}

// This model will have the `includePedigree` and `name` fields, but not `id` or `pedigree`.
model QueryDog is Query<Dog>;

Properties

None

Read

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

The “Read” lifecycle phase is used for properties returned by operations that read data, like HTTP GET operations.

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;

  @visibility(Lifecycle.Create, Lifecycle.Update)
  secretName: string;

  name: string;
}

// This model has the `id` and `name` fields, but not `secretName`.
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.

Update

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

The “Update” lifecycle phase is used for properties passed as parameters to operations that update data, like HTTP PATCH operations.

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;

  @visibility(Lifecycle.Create, Lifecycle.Update)
  secretName: string;

  name: string;
}

// This model will have the `secretName` and `name` fields, but not the `id` field.
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 as seconds
milliseconds	"milliseconds"	Encode to integer or float as milliseconds

Lifecycle

A visibility class for resource lifecycle phases.

These visibilities control whether a property is visible during the various phases of a resource’s lifecycle.

enum Lifecycle

Name	Value	Description
Create		The property is visible when a resource is being created.
Read		The property is visible when a resource is being read.
Update		The property is visible when a resource is being updated.
Delete		The property is visible when a resource is being deleted.
Query		The property is visible when a resource is being queried. In HTTP APIs, this visibility applies to parameters of GET or HEAD operations.

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