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

`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