Built-in Decorators
TypeSpec
@continuationToken
Pagination property defining the token to get to the next page. It MUST be specified both on the request parameter and the response.
@continuationToken
Target
ModelProperty
Parameters
None
Examples
model Page<T> { @pageItems items: T[]; @continuationToken continuationToken: string;}@list op listPets(@continuationToken continuationToken: string): Page<Pet>;
@defaultVisibility
Declares the default visibility modifiers for a visibility class.
The default modifiers are used when a property does not have any visibility decorators applied to it.
The modifiers passed to this decorator MUST be members of the target Enum.
@defaultVisibility(...visibilities: valueof EnumMember[])
Target
Enum
Parameters
Name | Type | Description |
---|---|---|
visibilities | valueof EnumMember[] | the list of modifiers to use as the default visibility modifiers. |
@deprecated
Mark this type as deprecated.
NOTE: This decorator should not be used, use the #deprecated
directive instead.
@deprecated(message: valueof string)
Target
unknown
Parameters
Name | Type | Description |
---|---|---|
message | valueof string | Deprecation message. |
Examples
Use the #deprecated
directive instead:
#deprecated "Use ActionV2"op Action<Result>(): Result;
@discriminator
Specify the property to be used to discriminate this type.
@discriminator(propertyName: valueof string)
Target
Model | Union
Parameters
Name | Type | Description |
---|---|---|
propertyName | valueof string | The property name to use for discrimination |
Examples
@discriminator("kind")union Pet{ cat: Cat, dog: Dog }
model Cat {kind: "cat", meow: boolean}model Dog {kind: "dog", bark: boolean}
@discriminator("kind")model Pet{ kind: string }
model Cat extends Pet {kind: "cat", meow: boolean}model Dog extends Pet {kind: "dog", bark: boolean}
@doc
Attach a documentation string.
@doc(doc: valueof string, formatArgs?: {})
Target
unknown
Parameters
Name | Type | Description |
---|---|---|
doc | valueof string | Documentation string |
formatArgs | {} | Record with key value pair that can be interpolated in the doc. |
Examples
@doc("Represent a Pet available in the PetStore")model Pet {}
@encode
Specify how to encode the target type.
@encode(encodingOrEncodeAs: Scalar | valueof string | EnumMember, encodedAs?: Scalar)
Target
Scalar | ModelProperty
Parameters
Name | Type | Description |
---|---|---|
encodingOrEncodeAs | Scalar | valueof string | EnumMember | Known name of an encoding or a scalar type to encode as(Only for numeric types to encode as string). |
encodedAs | Scalar | What target type is this being encoded as. Default to string. |
Examples
offsetDateTime encoded with rfc7231
@encode("rfc7231")scalar myDateTime extends offsetDateTime;
utcDateTime encoded with unixTimestamp
@encode("unixTimestamp", int32)scalar myDateTime extends unixTimestamp;
encode numeric type to string
model Pet { @encode(string) id: int64;}
@encodedName
Provide an alternative name for this type when serialized to the given mime type.
@encodedName(mimeType: valueof string, name: valueof string)
Target
unknown
Parameters
Name | Type | Description |
---|---|---|
mimeType | valueof string | Mime type this should apply to. The mime type should be a known mime type as described here https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types without any suffix (e.g. +json ) |
name | valueof string | Alternative name |
Examples
model Certificate { @encodedName("application/json", "exp") @encodedName("application/xml", "expiry") expireAt: int32;}
Invalid values
@encodedName("application/merge-patch+json", "exp") ^ error cannot use subtype
@error
Specify that this model is an error type. Operations return error types when the operation has failed.
@error
Target
Model
Parameters
None
Examples
@errormodel PetStoreError { code: string; message: string;}
@errorsDoc
Attach a documentation string to describe the error return types of an operation.
If an operation returns a union of success and errors it only describes the errors. See @returnsDoc
for success documentation.
@errorsDoc(doc: valueof string)
Target
Operation
Parameters
Name | Type | Description |
---|---|---|
doc | valueof string | Documentation string |
Examples
@errorsDoc("Errors doc")op get(): Pet | NotFound;
@example
Provide an example value for a data type.
@example(example: valueof unknown, options?: valueof ExampleOptions)
Target
Model | Enum | Scalar | Union | ModelProperty | UnionVariant
Parameters
Name | Type | Description |
---|---|---|
example | valueof unknown | Example value. |
options | valueof ExampleOptions | Optional metadata for the example. |
Examples
@example(#{name: "Fluffy", age: 2})model Pet { name: string; age: int32;}
@firstLink
Pagination property defining a link to the first page.
It is expected that navigating to the link will return the same set of responses as the operation that returned the current page.
@firstLink
Target
ModelProperty
Parameters
None
Examples
model Page<T> { @pageItems items: T[]; @nextLink next: url; @prevLink prev: url; @firstLink first: url; @lastLink last: url;}@list op listPets(): Page<Pet>;
@format
Specify a known data format hint for this string type. For example uuid
, uri
, etc.
This differs from the @pattern
decorator which is meant to specify a regular expression while @format
accepts a known format name.
The format names are open ended and are left to emitter to interpret.
@format(format: valueof string)
Target
string | bytes | ModelProperty
Parameters
Name | Type | Description |
---|---|---|
format | valueof string | format name. |
Examples
@format("uuid")scalar uuid extends string;
@friendlyName
Specifies how a templated type should name their instances.
@friendlyName(name: valueof string, formatArgs?: unknown)
Target
unknown
Parameters
Name | Type | Description |
---|---|---|
name | valueof string | name the template instance should take |
formatArgs | unknown | Model with key value used to interpolate the name |
Examples
@friendlyName("{name}List", T)model List<Item> { value: Item[]; nextLink: string;}
@inspectType
A debugging decorator used to inspect a type.
@inspectType(text: valueof string)
Target
unknown
Parameters
Name | Type | Description |
---|---|---|
text | valueof string | Custom text to log |
@inspectTypeName
A debugging decorator used to inspect a type name.
@inspectTypeName(text: valueof string)
Target
unknown
Parameters
Name | Type | Description |
---|---|---|
text | valueof string | Custom text to log |
@invisible
Indicates that a property is not visible in the given visibility class.
This decorator removes all active visibility modifiers from the property within the given visibility class.
@invisible(visibilityClass: Enum)
Target
ModelProperty
Parameters
Name | Type | Description |
---|---|---|
visibilityClass | Enum | The visibility class to make the property invisible within. |
Examples
model Example { @invisible(Lifecycle) hidden_property: string;}
@key
Mark a model property as the key to identify instances of that type
@key(altName?: valueof string)
Target
ModelProperty
Parameters
Name | Type | Description |
---|---|---|
altName | valueof string | Name of the property. If not specified, the decorated property name is used. |
Examples
model Pet { @key id: string;}
@knownValues
Provide a set of known values to a string type.
@knownValues(values: Enum)
Target
string | numeric | ModelProperty
Parameters
Name | Type | Description |
---|---|---|
values | Enum | Known values enum. |
Examples
@knownValues(KnownErrorCode)scalar ErrorCode extends string;
enum KnownErrorCode { NotFound, Invalid,}
@lastLink
Pagination property defining a link to the last page.
It is expected that navigating to the link will return the same set of responses as the operation that returned the current page.
@lastLink
Target
ModelProperty
Parameters
None
Examples
model Page<T> { @pageItems items: T[]; @nextLink next: url; @prevLink prev: url; @firstLink first: url; @lastLink last: url;}@list op listPets(): Page<Pet>;
@list
Mark this operation as a list
operation that returns a paginated list of items.
@list
Target
Operation
Parameters
None
@maxItems
Specify the maximum number of items this array should have.
@maxItems(value: valueof integer)
Target
unknown[] | ModelProperty
Parameters
Name | Type | Description |
---|---|---|
value | valueof integer | Maximum number |
Examples
@maxItems(5)model Endpoints is string[];
@maxLength
Specify the maximum length this string type should be.
@maxLength(value: valueof integer)
Target
string | ModelProperty
Parameters
Name | Type | Description |
---|---|---|
value | valueof integer | Maximum length |
Examples
@maxLength(20)scalar Username extends string;
@maxValue
Specify the maximum value this numeric type should be.
@maxValue(value: valueof numeric)
Target
numeric | ModelProperty
Parameters
Name | Type | Description |
---|---|---|
value | valueof numeric | Maximum value |
Examples
@maxValue(200)scalar Age is int32;
@maxValueExclusive
Specify the maximum value this numeric type should be, exclusive of the given value.
@maxValueExclusive(value: valueof numeric)
Target
numeric | ModelProperty
Parameters
Name | Type | Description |
---|---|---|
value | valueof numeric | Maximum value |
Examples
@maxValueExclusive(50)scalar distance is float64;
@minItems
Specify the minimum number of items this array should have.
@minItems(value: valueof integer)
Target
unknown[] | ModelProperty
Parameters
Name | Type | Description |
---|---|---|
value | valueof integer | Minimum number |
Examples
@minItems(1)model Endpoints is string[];
@minLength
Specify the minimum length this string type should be.
@minLength(value: valueof integer)
Target
string | ModelProperty
Parameters
Name | Type | Description |
---|---|---|
value | valueof integer | Minimum length |
Examples
@minLength(2)scalar Username extends string;
@minValue
Specify the minimum value this numeric type should be.
@minValue(value: valueof numeric)
Target
numeric | ModelProperty
Parameters
Name | Type | Description |
---|---|---|
value | valueof numeric | Minimum value |
Examples
@minValue(18)scalar Age is int32;
@minValueExclusive
Specify the minimum value this numeric type should be, exclusive of the given value.
@minValueExclusive(value: valueof numeric)
Target
numeric | ModelProperty
Parameters
Name | Type | Description |
---|---|---|
value | valueof numeric | Minimum value |
Examples
@minValueExclusive(0)scalar distance is float64;
@nextLink
Pagination property defining a link to the next page.
It is expected that navigating to the link will return the same set of responses as the operation that returned the current page.
@nextLink
Target
ModelProperty
Parameters
None
Examples
model Page<T> { @pageItems items: T[]; @nextLink next: url; @prevLink prev: url; @firstLink first: url; @lastLink last: url;}@list op listPets(): Page<Pet>;
@offset
Pagination property defining the number of items to skip.
@offset
Target
ModelProperty
Parameters
None
Examples
model Page<T> { @pageItems items: T[];}@list op listPets(@offset skip: int32, @pageSize pageSize: int8): Page<Pet>;
@opExample
Provide example values for an operation’s parameters and corresponding return type.
@opExample(example: valueof OperationExample, options?: valueof ExampleOptions)
Target
Operation
Parameters
Name | Type | Description |
---|---|---|
example | valueof OperationExample | Example value. |
options | valueof ExampleOptions | Optional metadata for the example. |
Examples
@opExample(#{parameters: #{name: "Fluffy", age: 2}, returnType: #{name: "Fluffy", age: 2, id: "abc"})op createPet(pet: Pet): Pet;
@overload
Specify this operation is an overload of the given operation.
@overload(overloadbase: Operation)
Target
Operation
Parameters
Name | Type | Description |
---|---|---|
overloadbase | Operation | Base operation that should be a union of all overloads |
Examples
op upload(data: string | bytes, @header contentType: "text/plain" | "application/octet-stream"): void;@overload(upload)op uploadString(data: string, @header contentType: "text/plain" ): void;@overload(upload)op uploadBytes(data: bytes, @header contentType: "application/octet-stream"): void;
@pageIndex
Pagination property defining the page index.
@pageIndex
Target
ModelProperty
Parameters
None
Examples
model Page<T> { @pageItems items: T[];}@list op listPets(@pageIndex page: int32, @pageSize pageSize: int8): Page<Pet>;
@pageItems
Specify the the property that contains the array of page items.
@pageItems
Target
ModelProperty
Parameters
None
Examples
model Page<T> { @pageItems items: T[];}@list op listPets(@pageIndex page: int32, @pageSize pageSize: int8): Page<Pet>;
@pageSize
Specify the pagination parameter that controls the maximum number of items to include in a page.
@pageSize
Target
ModelProperty
Parameters
None
Examples
model Page<T> { @pageItems items: T[];}@list op listPets(@pageIndex page: int32, @pageSize pageSize: int8): Page<Pet>;
@parameterVisibility
Sets which visibilities apply to parameters for the given operation.
@parameterVisibility(...visibilities: valueof string | EnumMember[])
Target
Operation
Parameters
Name | Type | Description |
---|---|---|
visibilities | valueof string | EnumMember[] | List of visibility strings which apply to this operation. |
@pattern
Specify the the pattern this string should respect using simple regular expression syntax.
The following syntax is allowed: alternations (|
), quantifiers (?
, *
, +
, and { }
), wildcard (.
), and grouping parentheses.
Advanced features like look-around, capture groups, and references are not supported.
This decorator may optionally provide a custom validation message. Emitters may choose to use the message to provide context when pattern validation fails. For the sake of consistency, the message should be a phrase that describes in plain language what sort of content the pattern attempts to validate. For example, a complex regular expression that validates a GUID string might have a message like “Must be a valid GUID.”
@pattern(pattern: valueof string, validationMessage?: valueof string)
Target
string | bytes | ModelProperty
Parameters
Name | Type | Description |
---|---|---|
pattern | valueof string | Regular expression. |
validationMessage | valueof string | Optional validation message that may provide context when validation fails. |
Examples
@pattern("[a-z]+", "Must be a string consisting of only lower case letters and of at least one character.")scalar LowerAlpha extends string;
@prevLink
Pagination property defining a link to the previous page.
It is expected that navigating to the link will return the same set of responses as the operation that returned the current page.
@prevLink
Target
ModelProperty
Parameters
None
Examples
model Page<T> { @pageItems items: T[]; @nextLink next: url; @prevLink prev: url; @firstLink first: url; @lastLink last: url;}@list op listPets(): Page<Pet>;
@projectedName
DEPRECATED: Use @encodedName
instead.
Provide an alternative name for this type.
@projectedName(targetName: valueof string, projectedName: valueof string)
Target
unknown
Parameters
Name | Type | Description |
---|---|---|
targetName | valueof string | Projection target |
projectedName | valueof string | Alternative name |
Examples
model Certificate { @projectedName("json", "exp") expireAt: int32;}
@removeVisibility
Removes visibility modifiers from a property.
If the visibility modifiers for a visibility class have not been initialized, this decorator will use the default visibility modifiers for the visibility class as the default modifier set.
@removeVisibility(...visibilities: valueof EnumMember[])
Target
The property to remove visibility from.
ModelProperty
Parameters
Name | Type | Description |
---|---|---|
visibilities | valueof EnumMember[] | The visibility modifiers to remove from the target property. |
Examples
model Example { // This property will have the Create and Update visibilities, but not the // Read visibility, since it is removed. @removeVisibility(Lifecycle.Read) secret_property: string;}
@returnsDoc
Attach a documentation string to describe the successful return types of an operation.
If an operation returns a union of success and errors it only describes the success. See @errorsDoc
for error documentation.
@returnsDoc(doc: valueof string)
Target
Operation
Parameters
Name | Type | Description |
---|---|---|
doc | valueof string | Documentation string |
Examples
@returnsDoc("Returns doc")op get(): Pet | NotFound;
@returnTypeVisibility
Sets which visibilities apply to the return type for the given operation.
@returnTypeVisibility(...visibilities: valueof string | EnumMember[])
Target
Operation
Parameters
Name | Type | Description |
---|---|---|
visibilities | valueof string | EnumMember[] | List of visibility strings which apply to this operation. |
@secret
Mark this string as a secret value that should be treated carefully to avoid exposure
@secret
Target
string | ModelProperty
Parameters
None
Examples
@secretscalar Password is string;
@service
Mark this namespace as describing a service and configure service properties.
@service(options?: ServiceOptions)
Target
Namespace
Parameters
Name | Type | Description |
---|---|---|
options | ServiceOptions | Optional configuration for the service. |
Examples
@servicenamespace PetStore;
Setting service title
@service({title: "Pet store"})namespace PetStore;
Setting service version
@service({version: "1.0"})namespace PetStore;
@summary
Typically a short, single-line description.
@summary(summary: valueof string)
Target
unknown
Parameters
Name | Type | Description |
---|---|---|
summary | valueof string | Summary string. |
Examples
@summary("This is a pet")model Pet {}
@tag
Attaches a tag to an operation, interface, or namespace. Multiple @tag
decorators can be specified to attach multiple tags to a TypeSpec element.
@tag(tag: valueof string)
Target
Namespace | Interface | Operation
Parameters
Name | Type | Description |
---|---|---|
tag | valueof string | Tag value |
@visibility
Indicates that a property is only considered to be present or applicable (“visible”) with the in the given named contexts (“visibilities”). When a property has no visibilities applied to it, it is implicitly visible always.
As far as the TypeSpec core library is concerned, visibilities are open-ended and can be arbitrary strings, but the following visibilities are well-known to standard libraries and should be used with standard emitters that interpret them as follows:
- “read”: output of any operation.
- “create”: input to operations that create an entity..
- “query”: input to operations that read data.
- “update”: input to operations that update data.
- “delete”: input to operations that delete data.
See also: Automatic visibility
@visibility(...visibilities: valueof string | EnumMember[])
Target
ModelProperty
Parameters
Name | Type | Description |
---|---|---|
visibilities | valueof string | EnumMember[] | List of visibilities which apply to this property. |
Examples
model Dog { // the service will generate an ID, so you don't need to send it. @visibility(Lifecycle.Read) id: int32; // the service will store this secret name, but won't ever return it @visibility(Lifecycle.Create, Lifecycle.Update) secretName: string; // the regular name is always present name: string;}
@withDefaultKeyVisibility
Set the visibility of key properties in a model if not already set.
This will set the visibility modifiers of all key properties in the model if the visibility is not already explicitly set, but will not change the visibility of any properties that have visibility set explicitly, even if the visibility is the same as the default visibility.
Visibility may be explicitly set using any of the following decorators:
@visibility
@removeVisibility
@invisible
@withDefaultKeyVisibility(visibility: valueof string | EnumMember)
Target
Model
Parameters
Name | Type | Description |
---|---|---|
visibility | valueof string | EnumMember | The desired default visibility value. If a key property already has visibility set, it will not be changed. |
@withLifecycleUpdate
Transforms the target
model to include only properties that are visible during the
“Update” lifecycle phase.
Any nested models of optional properties will be transformed into the “CreateOrUpdate” lifecycle phase instead of the “Update” lifecycle phase, so that nested models may be fully updated.
@withLifecycleUpdate
Target
The model to apply the transformation to.
Model
Parameters
None
Examples
model Dog { @visibility(Lifecycle.Read) id: int32;
@visibility(Lifecycle.Create, Lifecycle.Update) secretName: string;
name: string;}
@withLifecycleUpdatemodel DogUpdate { ...Dog}
@withOptionalProperties
Returns the model with required properties removed.
@withOptionalProperties
Target
Model
Parameters
None
@withoutDefaultValues
Returns the model with any default values removed.
@withoutDefaultValues
Target
Model
Parameters
None
@withoutOmittedProperties
Returns the model with the given properties omitted.
@withoutOmittedProperties(omit: string | Union)
Target
Model
Parameters
Name | Type | Description |
---|---|---|
omit | string | Union | List of properties to omit |
@withPickedProperties
Returns the model with only the given properties included.
@withPickedProperties(pick: string | Union)
Target
Model
Parameters
Name | Type | Description |
---|---|---|
pick | string | Union | List of properties to include |
@withUpdateableProperties
Returns the model with non-updateable properties removed.
@withUpdateableProperties
Target
Model
Parameters
None
@withVisibility
Removes properties that are not considered to be present or applicable (“visible”) in the given named contexts (“visibilities”). Can be used together with spread to effectively spread only visible properties into a new model.
See also: Automatic visibility
When using an emitter that applies visibility automatically, it is generally not necessary to use this decorator.
@withVisibility(...visibilities: valueof string | EnumMember[])
Target
Model
Parameters
Name | Type | Description |
---|---|---|
visibilities | valueof string | EnumMember[] | List of visibilities which apply to this property. |
Examples
model Dog { @visibility("read") id: int32; @visibility("create", "update") secretName: string; name: string;}
// The spread operator will copy all the properties of Dog into DogRead,// and @withVisibility will then remove those that are not visible with// create or update visibility.//// In this case, the id property is removed, and the name and secretName// properties are kept.@withVisibility("create", "update")model DogCreateOrUpdate { ...Dog;}
// In this case the id and name properties are kept and the secretName property// is removed.@withVisibility("read")model DogRead { ...Dog;}
@withVisibilityFilter
Applies the given visibility filter to the properties of the target model.
This transformation is recursive, so it will also apply the filter to any nested
or referenced models that are the types of any properties in the target
.
@withVisibilityFilter(filter: valueof VisibilityFilter)
Target
The model to apply the visibility filter to.
Model
Parameters
Name | Type | Description |
---|---|---|
filter | valueof VisibilityFilter | The visibility filter to apply to the properties of the target model. |
Examples
model Dog { @visibility(Lifecycle.Read) id: int32;
name: string;}
@withVisibilityFilter(#{ all: #[Lifecycle.Read] })model DogRead { ...Dog}