Built-in Data types
TypeSpec
Section titled âTypeSpecâmodel Array<Element>
Template Parameters
Section titled âTemplate ParametersâName | Description |
---|---|
Element | The type of the array elements |
Properties
Section titled âPropertiesâ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>
Template Parameters
Section titled âTemplate ParametersâName | Description |
---|---|
T | The model to transform. |
NameTemplate | The name template to use for the new model. * |
Examples
Section titled âExamplesâmodel Dog { @visibility(Lifecycle.Read) id: int32;
name: string;}
// This model has only the `name` field.model CreateDog is Create<Dog>;
Properties
Section titled âPropertiesâNone
CreateOrUpdate
Section titled â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
Section titled âTemplate ParametersâName | Description |
---|---|
T | The model to transform. |
NameTemplate | The name template to use for the new model. * |
Examples
Section titled â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
Section titled âPropertiesâNone
DefaultKeyVisibility
Section titled âDefaultKeyVisibilityâApplies a visibility setting to a collection of properties.
model DefaultKeyVisibility<Source, Visibility>
Template Parameters
Section titled âTemplate ParametersâName | Description |
---|---|
Source | An object whose properties are spread. |
Visibility | The visibility to apply to all properties. |
Properties
Section titled â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>
Template Parameters
Section titled âTemplate ParametersâName | Description |
---|---|
T | The model to transform. |
NameTemplate | The name template to use for the new model. * |
Examples
Section titled â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
Section titled âPropertiesâNone
DiscriminatedOptions
Section titled âDiscriminatedOptionsâOptions for @discriminated
decorator.
model DiscriminatedOptions
Properties
Section titled â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
Section titled âExampleOptionsâOptions for example decorators
model ExampleOptions
Properties
Section titled âPropertiesâName | Type | Description |
---|---|---|
title? | string | The title of the example |
description? | string | Description of the example |
OmitDefaults
Section titled âOmitDefaultsâRepresents a collection of properties with default values omitted.
model OmitDefaults<Source>
Template Parameters
Section titled âTemplate ParametersâName | Description |
---|---|
Source | An object whose spread property defaults are all omitted. |
Properties
Section titled âPropertiesâNone
OmitProperties
Section titled âOmitPropertiesâRepresents a collection of omitted properties.
model OmitProperties<Source, Keys>
Template Parameters
Section titled âTemplate ParametersâName | Description |
---|---|
Source | An object whose properties are spread. |
Keys | The property keys to omit. |
Properties
Section titled âPropertiesâNone
OperationExample
Section titled âOperationExampleâOperation example configuration.
model OperationExample
Properties
Section titled âPropertiesâName | Type | Description |
---|---|---|
parameters? | unknown | Example request body. |
returnType? | unknown | Example response body. |
OptionalProperties
Section titled âOptionalPropertiesâRepresents a collection of optional properties.
model OptionalProperties<Source>
Template Parameters
Section titled âTemplate ParametersâName | Description |
---|---|
Source | An object whose spread properties are all optional. |
Properties
Section titled âPropertiesâNone
PickProperties
Section titled âPickPropertiesâRepresents a collection of properties with only the specified keys included.
model PickProperties<Source, Keys>
Template Parameters
Section titled âTemplate ParametersâName | Description |
---|---|
Source | An object whose properties are spread. |
Keys | The property keys to include. |
Properties
Section titled âPropertiesâ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>
Template Parameters
Section titled âTemplate ParametersâName | Description |
---|---|
T | The model to transform. |
NameTemplate | The name template to use for the new model. * |
Examples
Section titled â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
Section titled âPropertiesâ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>
Template Parameters
Section titled âTemplate ParametersâName | Description |
---|---|
T | The model to transform. |
NameTemplate | The name template to use for the new model. * |
Examples
Section titled â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
Section titled âPropertiesâNone
model Record<Element>
Template Parameters
Section titled âTemplate ParametersâName | Description |
---|---|
Element | The type of the properties |
Properties
Section titled âPropertiesâNone
ServiceOptions
Section titled âServiceOptionsâService options.
model ServiceOptions
Properties
Section titled âPropertiesâName | Type | Description |
---|---|---|
title? | string | Title 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>
Template Parameters
Section titled âTemplate ParametersâName | Description |
---|---|
T | The model to transform. |
NameTemplate | The name template to use for the new model. * |
Examples
Section titled â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
Section titled âPropertiesâNone
UpdateableProperties
Section titled âUpdateablePropertiesâRepresents a collection of updateable properties.
model UpdateableProperties<Source>
Template Parameters
Section titled âTemplate ParametersâName | Description |
---|---|
Source | An object whose spread properties are all updateable. |
Properties
Section titled âPropertiesâNone
VisibilityFilter
Section titled â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
Section titled âPropertiesâName | Type | Description |
---|---|---|
any? | EnumMember[] | |
all? | EnumMember[] | |
none? | EnumMember[] |
ArrayEncoding
Section titled â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
Section titled âBytesKnownEncodingâKnown encoding to use on bytes
enum BytesKnownEncoding
Name | Value | Description |
---|---|---|
base64 | "base64" | Encode to Base64 |
base64url | "base64url" | Encode to Base64 Url |
DateTimeKnownEncoding
Section titled â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
Section titled âDurationKnownEncodingâKnown encoding to use on duration
enum DurationKnownEncoding
Name | Value | Description |
---|---|---|
ISO8601 | "ISO8601" | ISO8601 duration |
seconds | "seconds" | Encode to integer or float |
Lifecycle
Section titled â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
Section titled â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
Section titled âbooleanâBoolean with true
and false
values.
scalar boolean
Represent a byte array
scalar bytes
decimal
Section titled â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
Section titled âdecimal128âA 128-bit decimal number.
scalar decimal128
duration
Section titled âdurationâA duration/time period. e.g 5s, 10h
scalar duration
A number with decimal value
scalar float
float32
Section titled âfloat32âA 32 bit floating point number. (±1.5 x 10^â45
to ±3.4 x 10^38
)
scalar float32
float64
Section titled âfloat64â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
integer
Section titled âintegerâA whole number. This represent any integer
value possible.
It is commonly represented as BigInteger
in some languages.
scalar integer
numeric
Section titled ânumericâA numeric type
scalar numeric
offsetDateTime
Section titled âoffsetDateTimeâA date and time in a particular time zone, e.g. âApril 10th at 3:00am in PSTâ
scalar offsetDateTime
plainDate
Section titled âplainDateâA date on a calendar without a time zone, e.g. âApril 10thâ
scalar plainDate
plainTime
Section titled âplainTimeâA time on a clock without a time zone, e.g. â3:00 amâ
scalar plainTime
safeint
Section titled âsafeintâ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
unixTimestamp32
Section titled â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
Represent a URL string as described by https://url.spec.whatwg.org/
scalar url
utcDateTime
Section titled âutcDateTimeâAn instant in coordinated universal time (UTC)â
scalar utcDateTime