Skip to content

Built-in Decorators

Pagination property defining the token to get to the next page. It MUST be specified both on the request parameter and the response.

@continuationToken

ModelProperty

None

model Page<T> {
@pageItems items: T[];
@continuationToken continuationToken: string;
}
@list op listPets(@continuationToken continuationToken: string): Page<Pet>;

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[])

Enum

NameTypeDescription
visibilitiesvalueof EnumMember[]the list of modifiers to use as the default visibility modifiers.

Specify that this union is discriminated.

@discriminated(options?: valueof DiscriminatedOptions)

Union

NameTypeDescription
optionsvalueof DiscriminatedOptionsOptions to configure the serialization of the discriminated union.
@discriminated
union Pet{ cat: Cat, dog: Dog }
model Cat { name: string, meow: boolean }
model Dog { name: string, bark: boolean }

Serialized as:

{
"kind": "cat",
"value": {
"name": "Whiskers",
"meow": true
}
},
{
"kind": "dog",
"value": {
"name": "Rex",
"bark": false
}
}
@discriminated(#{discriminatorPropertyName: "dataKind", envelopePropertyName: "data"})
union Pet{ cat: Cat, dog: Dog }
model Cat { name: string, meow: boolean }
model Dog { name: string, bark: boolean }

Serialized as:

{
"dataKind": "cat",
"data": {
"name": "Whiskers",
"meow": true
}
},
{
"dataKind": "dog",
"data": {
"name": "Rex",
"bark": false
}
}

Specify the property to be used to discriminate this type.

@discriminator(propertyName: valueof string)

Model

NameTypeDescription
propertyNamevalueof stringThe property name to use for discrimination
@discriminator("kind")
model Pet{ kind: string }
model Cat extends Pet {kind: "cat", meow: boolean}
model Dog extends Pet {kind: "dog", bark: boolean}

Attach a documentation string. Content support CommonMark markdown formatting.

@doc(doc: valueof string, formatArgs?: {})

unknown

NameTypeDescription
docvalueof stringDocumentation string
formatArgs{}Record with key value pair that can be interpolated in the doc.
@doc("Represent a Pet available in the PetStore")
model Pet {}

Specify how to encode the target type.

@encode(encodingOrEncodeAs: Scalar | valueof string | EnumMember, encodedAs?: Scalar)

Scalar | ModelProperty

NameTypeDescription
encodingOrEncodeAsScalar | valueof string | EnumMemberKnown name of an encoding or a scalar type to encode as(Only for numeric types to encode as string).
encodedAsScalarWhat target type is this being encoded as. Default to string.
@encode("rfc7231")
scalar myDateTime extends offsetDateTime;
@encode("unixTimestamp", int32)
scalar myDateTime extends unixTimestamp;
model Pet {
@encode(string) id: int64;
}

Provide an alternative name for this type when serialized to the given mime type.

@encodedName(mimeType: valueof string, name: valueof string)

unknown

NameTypeDescription
mimeTypevalueof stringMime 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)
namevalueof stringAlternative name
model Certificate {
@encodedName("application/json", "exp")
@encodedName("application/xml", "expiry")
expireAt: int32;
}
@encodedName("application/merge-patch+json", "exp")
^ error cannot use subtype

Specify that this model is an error type. Operations return error types when the operation has failed.

@error

Model

None

@error
model PetStoreError {
code: string;
message: string;
}

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)

Operation

NameTypeDescription
docvalueof stringDocumentation string
@errorsDoc("Errors doc")
op get(): Pet | NotFound;

Provide an example value for a data type.

@example(example: valueof unknown, options?: valueof ExampleOptions)

Model | Enum | Scalar | Union | ModelProperty | UnionVariant

NameTypeDescription
examplevalueof unknownExample value.
optionsvalueof ExampleOptionsOptional metadata for the example.
@example(#{name: "Fluffy", age: 2})
model Pet {
name: string;
age: int32;
}

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

ModelProperty

None

model Page<T> {
@pageItems items: T[];
@nextLink next: url;
@prevLink prev: url;
@firstLink first: url;
@lastLink last: url;
}
@list op listPets(): Page<Pet>;

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)

string | ModelProperty

NameTypeDescription
formatvalueof stringformat name.
@format("uuid")
scalar uuid extends string;

Specifies how a templated type should name their instances.

@friendlyName(name: valueof string, formatArgs?: unknown)

unknown

NameTypeDescription
namevalueof stringname the template instance should take
formatArgsunknownModel with key value used to interpolate the name
@friendlyName("{name}List", T)
model List<Item> {
value: Item[];
nextLink: string;
}

A debugging decorator used to inspect a type.

@inspectType(text: valueof string)

unknown

NameTypeDescription
textvalueof stringCustom text to log

A debugging decorator used to inspect a type name.

@inspectTypeName(text: valueof string)

unknown

NameTypeDescription
textvalueof stringCustom text to log

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, making it invisible to any context that selects for visibility modifiers within that class.

@invisible(visibilityClass: Enum)

ModelProperty

NameTypeDescription
visibilityClassEnumThe visibility class to make the property invisible within.
model Example {
@invisible(Lifecycle)
hidden_property: string;
}

Mark a model property as the key to identify instances of that type

@key(altName?: valueof string)

ModelProperty

NameTypeDescription
altNamevalueof stringName of the property. If not specified, the decorated property name is used.
model Pet {
@key id: string;
}

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

ModelProperty

None

model Page<T> {
@pageItems items: T[];
@nextLink next: url;
@prevLink prev: url;
@firstLink first: url;
@lastLink last: url;
}
@list op listPets(): Page<Pet>;

Mark this operation as a list operation that returns a paginated list of items.

@list

Operation

None

Specify the maximum number of items this array should have.

@maxItems(value: valueof integer)

unknown[] | ModelProperty

NameTypeDescription
valuevalueof integerMaximum number
@maxItems(5)
model Endpoints is string[];

Specify the maximum length this string type should be.

@maxLength(value: valueof integer)

string | ModelProperty

NameTypeDescription
valuevalueof integerMaximum length
@maxLength(20)
scalar Username extends string;

Specify the maximum value this numeric type should be.

@maxValue(value: valueof numeric)

numeric | ModelProperty

NameTypeDescription
valuevalueof numericMaximum value
@maxValue(200)
scalar Age is int32;

Specify the maximum value this numeric type should be, exclusive of the given value.

@maxValueExclusive(value: valueof numeric)

numeric | ModelProperty

NameTypeDescription
valuevalueof numericMaximum value
@maxValueExclusive(50)
scalar distance is float64;

Applies a media type hint to a TypeSpec type. Emitters and libraries may choose to use this hint to determine how a type should be serialized. For example, the @typespec/http library will use the media type hint of the response body type as a default Content-Type if one is not explicitly specified in the operation.

Media types (also known as MIME types) are defined by RFC 6838. The media type hint should be a valid media type string as defined by the RFC, but the decorator does not enforce or validate this constraint.

Notes: the applied media type is only a hint. It may be overridden or not used at all. Media type hints are inherited by subtypes. If a media type hint is applied to a model, it will be inherited by all other models that extend it unless they delcare their own media type hint.

@mediaTypeHint(mediaType: valueof string)

Model | Scalar | Enum | Union

NameTypeDescription
mediaTypevalueof stringThe media type hint to apply to the target type.
create a model that serializes as XML by default
Section titled “create a model that serializes as XML by default”
@mediaTypeHint("application/xml")
model Example {
@visibility(Lifecycle.Read)
id: string;
name: string;
}

Specify the minimum number of items this array should have.

@minItems(value: valueof integer)

unknown[] | ModelProperty

NameTypeDescription
valuevalueof integerMinimum number
@minItems(1)
model Endpoints is string[];

Specify the minimum length this string type should be.

@minLength(value: valueof integer)

string | ModelProperty

NameTypeDescription
valuevalueof integerMinimum length
@minLength(2)
scalar Username extends string;

Specify the minimum value this numeric type should be.

@minValue(value: valueof numeric)

numeric | ModelProperty

NameTypeDescription
valuevalueof numericMinimum value
@minValue(18)
scalar Age is int32;

Specify the minimum value this numeric type should be, exclusive of the given value.

@minValueExclusive(value: valueof numeric)

numeric | ModelProperty

NameTypeDescription
valuevalueof numericMinimum value
@minValueExclusive(0)
scalar distance is float64;

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

ModelProperty

None

model Page<T> {
@pageItems items: T[];
@nextLink next: url;
@prevLink prev: url;
@firstLink first: url;
@lastLink last: url;
}
@list op listPets(): Page<Pet>;

Pagination property defining the number of items to skip.

@offset

ModelProperty

None

model Page<T> {
@pageItems items: T[];
}
@list op listPets(@offset skip: int32, @pageSize pageSize: int8): Page<Pet>;

Provide example values for an operation’s parameters and corresponding return type.

@opExample(example: valueof OperationExample, options?: valueof ExampleOptions)

Operation

NameTypeDescription
examplevalueof OperationExampleExample value.
optionsvalueof ExampleOptionsOptional metadata for the example.
@opExample(#{parameters: #{name: "Fluffy", age: 2}, returnType: #{name: "Fluffy", age: 2, id: "abc"})
op createPet(pet: Pet): Pet;

Specify this operation is an overload of the given operation.

@overload(overloadbase: Operation)

Operation

NameTypeDescription
overloadbaseOperationBase operation that should be a union of all overloads
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;

Pagination property defining the page index.

@pageIndex

ModelProperty

None

model Page<T> {
@pageItems items: T[];
}
@list op listPets(@pageIndex page: int32, @pageSize pageSize: int8): Page<Pet>;

Specify the the property that contains the array of page items.

@pageItems

ModelProperty

None

model Page<T> {
@pageItems items: T[];
}
@list op listPets(@pageIndex page: int32, @pageSize pageSize: int8): Page<Pet>;

Specify the pagination parameter that controls the maximum number of items to include in a page.

@pageSize

ModelProperty

None

model Page<T> {
@pageItems items: T[];
}
@list op listPets(@pageIndex page: int32, @pageSize pageSize: int8): Page<Pet>;

Declares the visibility constraint of the parameters of a given operation.

A parameter or property nested within a parameter will be visible if it has any of the visibilities in the list.

It is invalid to call this decorator with no visibility modifiers.

@parameterVisibility(...visibilities: valueof EnumMember[])

Operation

NameTypeDescription
visibilitiesvalueof EnumMember[]List of visibility modifiers that apply to the parameters of this operation.

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)

string | bytes | ModelProperty

NameTypeDescription
patternvalueof stringRegular expression.
validationMessagevalueof stringOptional validation message that may provide context when validation fails.
@pattern("[a-z]+", "Must be a string consisting of only lower case letters and of at least one character.")
scalar LowerAlpha extends string;

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

ModelProperty

None

model Page<T> {
@pageItems items: T[];
@nextLink next: url;
@prevLink prev: url;
@firstLink first: url;
@lastLink last: url;
}
@list op listPets(): Page<Pet>;

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[])

The property to remove visibility from. ModelProperty

NameTypeDescription
visibilitiesvalueof EnumMember[]The visibility modifiers to remove from the target property.
model Example {
// This property will have all Lifecycle visibilities except the Read
// visibility, since it is removed.
@removeVisibility(Lifecycle.Read)
secret_property: string;
}

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)

Operation

NameTypeDescription
docvalueof stringDocumentation string
@returnsDoc("Returns doc")
op get(): Pet | NotFound;

Declares the visibility constraint of the return type of a given operation.

A property within the return type of the operation will be visible if it has any of the visibilities in the list.

It is invalid to call this decorator with no visibility modifiers.

@returnTypeVisibility(...visibilities: valueof EnumMember[])

Operation

NameTypeDescription
visibilitiesvalueof EnumMember[]List of visibility modifiers that apply to the return type of this operation.

Mark this string as a secret value that should be treated carefully to avoid exposure

@secret

string | ModelProperty

None

@secret
scalar Password is string;

Mark this namespace as describing a service and configure service properties.

@service(options?: valueof ServiceOptions)

Namespace

NameTypeDescription
optionsvalueof ServiceOptionsOptional configuration for the service.
@service
namespace PetStore;
@service(#{title: "Pet store"})
namespace PetStore;
@service(#{version: "1.0"})
namespace PetStore;

Typically a short, single-line description.

@summary(summary: valueof string)

unknown

NameTypeDescription
summaryvalueof stringSummary string.
@summary("This is a pet")
model Pet {}

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)

Namespace | Interface | Operation

NameTypeDescription
tagvalueof stringTag value

Sets the visibility modifiers that are active on a property, indicating that it is only considered to be present (or “visible”) in contexts that select for the given modifiers.

A property without any visibility settings applied for any visibility class (e.g. Lifecycle) is considered to have the default visibility settings for that class.

If visibility for the property has already been set for a visibility class (for example, using @invisible or @removeVisibility), this decorator will add the specified visibility modifiers to the property.

See: Visibility

The @typespec/http library uses Lifecycle visibility to determine which properties are included in the request or response bodies of HTTP operations. By default, it uses the following visibility settings:

  • For the return type of operations, properties are included if they have Lifecycle.Read visibility.
  • For POST operation parameters, properties are included if they have Lifecycle.Create visibility.
  • For PUT operation parameters, properties are included if they have Lifecycle.Create or Lifecycle.Update visibility.
  • For PATCH operation parameters, properties are included if they have Lifecycle.Update visibility.
  • For DELETE operation parameters, properties are included if they have Lifecycle.Delete visibility.
  • For GET or HEAD operation parameters, properties are included if they have Lifecycle.Query visibility.

By default, properties have all five Lifecycle visibility modifiers enabled, so a property is visible in all contexts by default.

The default settings may be overridden using the @returnTypeVisibility and @parameterVisibility decorators.

See also: Automatic visibility

@visibility(...visibilities: valueof EnumMember[])

ModelProperty

NameTypeDescription
visibilitiesvalueof EnumMember[]List of visibilities which apply to this property.
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 has all vi
name: string;
}

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 set explicitly using any of the following decorators:

  • @visibility
  • @removeVisibility
  • @invisible
@withDefaultKeyVisibility(visibility: valueof EnumMember)

Model

NameTypeDescription
visibilityvalueof EnumMemberThe desired default visibility value. If a key property already has visibility set, it will not be changed.

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.

If a nameTemplate is provided, newly-created type instances will be named according to the template. See the @friendlyName decorator for more information on the template syntax. The transformed type is provided as the argument to the template.

@withLifecycleUpdate(nameTemplate?: valueof string)

The model to apply the transformation to. Model

NameTypeDescription
nameTemplatevalueof stringThe name template to use when renaming new model instances.
model Dog {
@visibility(Lifecycle.Read)
id: int32;
@visibility(Lifecycle.Create, Lifecycle.Update)
secretName: string;
name: string;
}
@withLifecycleUpdate
model DogUpdate {
...Dog
}

Returns the model with required properties removed.

@withOptionalProperties

Model

None

Returns the model with any default values removed.

@withoutDefaultValues

Model

None

Returns the model with the given properties omitted.

@withoutOmittedProperties(omit: string | Union)

Model

NameTypeDescription
omitstring | UnionList of properties to omit

Returns the model with only the given properties included.

@withPickedProperties(pick: string | Union)

Model

NameTypeDescription
pickstring | UnionList of properties to include

Returns the model with non-updateable properties removed.

@withUpdateableProperties

Model

None

Removes properties that do not have at least one of the given visibility modifiers active.

If no visibility modifiers are supplied, this decorator has no effect.

See also: Automatic visibility

When using an emitter that applies visibility automatically, it is generally not necessary to use this decorator.

@withVisibility(...visibilities: valueof EnumMember[])

Model

NameTypeDescription
visibilitiesvalueof EnumMember[]List of visibilities that apply to this property.
model Dog {
@visibility(Lifecycle.Read)
id: int32;
@visibility(Lifecycle.Create, Lifecycle.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(Lifecycle.Create, Lifecycle.Update)
model DogCreateOrUpdate {
...Dog;
}
// In this case the id and name properties are kept and the secretName property
// is removed.
@withVisibility(Lifecycle.Read)
model DogRead {
...Dog;
}

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.

If a nameTemplate is provided, newly-created type instances will be named according to the template. See the @friendlyName decorator for more information on the template syntax. The transformed type is provided as the argument to the template.

@withVisibilityFilter(filter: valueof VisibilityFilter, nameTemplate?: valueof string)

The model to apply the visibility filter to. Model

NameTypeDescription
filtervalueof VisibilityFilterThe visibility filter to apply to the properties of the target model.
nameTemplatevalueof stringThe name template to use when renaming new model instances.
model Dog {
@visibility(Lifecycle.Read)
id: int32;
name: string;
}
@withVisibilityFilter(#{ all: #[Lifecycle.Read] })
model DogRead {
...Dog
}