Skip to content

Built-in Data types

model Array<Element>
NameDescription
ElementThe type of the array elements

None

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>
NameDescription
TThe model to transform.
NameTemplateThe name template to use for the new model.

*
model Dog {
@visibility(Lifecycle.Read)
id: int32;
name: string;
}
// This model has only the `name` field.
model CreateDog is Create<Dog>;

None

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>
NameDescription
TThe model to transform.
NameTemplateThe name template to use for the new model.

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

None

Applies a visibility setting to a collection of properties.

model DefaultKeyVisibility<Source, Visibility>
NameDescription
SourceAn object whose properties are spread.
VisibilityThe visibility to apply to all properties.

None

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>
NameDescription
TThe model to transform.
NameTemplateThe name template to use for the new model.

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

None

Options for @discriminated decorator.

model DiscriminatedOptions
NameTypeDescription
envelope?"object" | "none"How is the discriminated union serialized.
discriminatorPropertyName?stringName of the discriminator property
envelopePropertyName?stringName of the property envelopping the data

Options for example decorators

model ExampleOptions
NameTypeDescription
title?stringThe title of the example
description?stringDescription of the example

Represents a collection of properties with default values omitted.

model OmitDefaults<Source>
NameDescription
SourceAn object whose spread property defaults are all omitted.

None

Represents a collection of omitted properties.

model OmitProperties<Source, Keys>
NameDescription
SourceAn object whose properties are spread.
KeysThe property keys to omit.

None

Operation example configuration.

model OperationExample
NameTypeDescription
parameters?unknownExample request body.
returnType?unknownExample response body.

Represents a collection of optional properties.

model OptionalProperties<Source>
NameDescription
SourceAn object whose spread properties are all optional.

None

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

model PickProperties<Source, Keys>
NameDescription
SourceAn object whose properties are spread.
KeysThe property keys to include.

None

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>
NameDescription
TThe model to transform.
NameTemplateThe name template to use for the new model.

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

None

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>
NameDescription
TThe model to transform.
NameTemplateThe name template to use for the new model.

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

None

model Record<Element>
NameDescription
ElementThe type of the properties

None

Service options.

model ServiceOptions
NameTypeDescription
title?stringTitle of the service.

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>
NameDescription
TThe model to transform.
NameTemplateThe name template to use for the new model.

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

None

Represents a collection of updateable properties.

model UpdateableProperties<Source>
NameDescription
SourceAn object whose spread properties are all updateable.

None

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
NameTypeDescription
any?EnumMember[]
all?EnumMember[]
none?EnumMember[]

Encoding for serializing arrays

enum ArrayEncoding
NameValueDescription
pipeDelimitedEach values of the array is separated by a |
spaceDelimitedEach values of the array is separated by a

Known encoding to use on bytes

enum BytesKnownEncoding
NameValueDescription
base64"base64"Encode to Base64
base64url"base64url"Encode to Base64 Url

Known encoding to use on utcDateTime or offsetDateTime

enum DateTimeKnownEncoding
NameValueDescription
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.

Known encoding to use on duration

enum DurationKnownEncoding
NameValueDescription
ISO8601"ISO8601"ISO8601 duration
seconds"seconds"Encode to integer or float

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
NameValueDescription
CreateThe property is visible when a resource is being created.
ReadThe property is visible when a resource is being read.
UpdateThe property is visible when a resource is being updated.
DeleteThe property is visible when a resource is being deleted.
QueryThe property is visible when a resource is being queried.

In HTTP APIs, this visibility applies to parameters of GET or HEAD operations.
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 with true and false values.

scalar boolean

Represent a byte array

scalar bytes

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

A 128-bit decimal number.

scalar decimal128

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

scalar duration

A number with decimal value

scalar float

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

scalar float32

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

scalar float64

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

scalar int16

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

scalar int32

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

scalar int64

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

scalar int8

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

scalar integer

A numeric type

scalar numeric

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

scalar offsetDateTime

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

scalar plainDate

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

scalar plainTime

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

scalar safeint

A sequence of textual characters.

scalar string

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

scalar uint16

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

scalar uint32

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

scalar uint64

A 8-bit unsigned integer (0 to 255)

scalar uint8

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

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

scalar url

An instant in coordinated universal time (UTC)”

scalar utcDateTime