Built-in Decorators
TypeSpec
@deprecated
Deprecated: @deprecated decorator is deprecated. Use the #deprecated
directive instead.
Mark this type as deprecated.
NOTE: This decorator should not be used, use the #deprecated
directive instead.
Target
unknown
Parameters
Name | Type | Description |
---|---|---|
message | valueof string | Deprecation message. |
Examples
Use the #deprecated
directive instead:
@discriminator
Specify the property to be used to discriminate this type.
Target
Model | Union
Parameters
Name | Type | Description |
---|---|---|
propertyName | valueof string | The property name to use for discrimination |
Examples
@doc
Attach a documentation string.
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
@encode
Specify how to encode the target type.
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
utcDateTime encoded with unixTimestamp
encode numeric type to string
@encodedName
Provide an alternative name for this type when serialized to the given mime type.
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
Invalid values
@error
Specify that this model is an error type. Operations return error types when the operation has failed.
Target
Model
Parameters
None
Examples
@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.
Target
Operation
Parameters
Name | Type | Description |
---|---|---|
doc | valueof string | Documentation string |
Examples
@example
Provide an example value for a data type.
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
@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.
Target
string | bytes | ModelProperty
Parameters
Name | Type | Description |
---|---|---|
format | valueof string | format name. |
Examples
@friendlyName
Specifies how a templated type should name their instances.
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
@inspectType
A debugging decorator used to inspect a type.
Target
unknown
Parameters
Name | Type | Description |
---|---|---|
text | valueof string | Custom text to log |
@inspectTypeName
A debugging decorator used to inspect a type name.
Target
unknown
Parameters
Name | Type | Description |
---|---|---|
text | valueof string | Custom text to log |
@key
Mark a model property as the key to identify instances of that type
Target
ModelProperty
Parameters
Name | Type | Description |
---|---|---|
altName | valueof string | Name of the property. If not specified, the decorated property name is used. |
Examples
@knownValues
Deprecated: This decorator has been deprecated. Use a named union of string literals with a string variant to achieve the same result without a decorator.
Provide a set of known values to a string type.
Target
string | numeric | ModelProperty
Parameters
Name | Type | Description |
---|---|---|
values | Enum | Known values enum. |
Examples
@list
Mark this operation as a list
operation for resource types.
Target
Operation
Parameters
Name | Type | Description |
---|---|---|
listedType | Model | Optional type of the items in the list. |
@maxItems
Specify the maximum number of items this array should have.
Target
unknown[] | ModelProperty
Parameters
Name | Type | Description |
---|---|---|
value | valueof integer | Maximum number |
Examples
@maxLength
Specify the maximum length this string type should be.
Target
string | ModelProperty
Parameters
Name | Type | Description |
---|---|---|
value | valueof integer | Maximum length |
Examples
@maxValue
Specify the maximum value this numeric type should be.
Target
numeric | ModelProperty
Parameters
Name | Type | Description |
---|---|---|
value | valueof numeric | Maximum value |
Examples
@maxValueExclusive
Specify the maximum value this numeric type should be, exclusive of the given value.
Target
numeric | ModelProperty
Parameters
Name | Type | Description |
---|---|---|
value | valueof numeric | Maximum value |
Examples
@minItems
Specify the minimum number of items this array should have.
Target
unknown[] | ModelProperty
Parameters
Name | Type | Description |
---|---|---|
value | valueof integer | Minimum number |
Examples
@minLength
Specify the minimum length this string type should be.
Target
string | ModelProperty
Parameters
Name | Type | Description |
---|---|---|
value | valueof integer | Minimum length |
Examples
@minValue
Specify the minimum value this numeric type should be.
Target
numeric | ModelProperty
Parameters
Name | Type | Description |
---|---|---|
value | valueof numeric | Minimum value |
Examples
@minValueExclusive
Specify the minimum value this numeric type should be, exclusive of the given value.
Target
numeric | ModelProperty
Parameters
Name | Type | Description |
---|---|---|
value | valueof numeric | Minimum value |
Examples
@opExample
Provide example values for an operation’s parameters and corresponding return type.
Target
Operation
Parameters
Name | Type | Description |
---|---|---|
example | valueof OperationExample | Example value. |
options | valueof ExampleOptions | Optional metadata for the example. |
Examples
@overload
Specify this operation is an overload of the given operation.
Target
Operation
Parameters
Name | Type | Description |
---|---|---|
overloadbase | Operation | Base operation that should be a union of all overloads |
Examples
@parameterVisibility
Sets which visibilities apply to parameters for the given operation.
Target
Operation
Parameters
Name | Type | Description |
---|---|---|
visibilities | valueof string[] | 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.”
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
@projectedName
Deprecated: Use @encodedName
instead for changing the name over the wire.
DEPRECATED: Use @encodedName
instead.
Provide an alternative name for this type.
Target
unknown
Parameters
Name | Type | Description |
---|---|---|
targetName | valueof string | Projection target |
projectedName | valueof string | Alternative name |
Examples
@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.
Target
Operation
Parameters
Name | Type | Description |
---|---|---|
doc | valueof string | Documentation string |
Examples
@returnTypeVisibility
Sets which visibilities apply to the return type for the given operation.
Target
Operation
Parameters
Name | Type | Description |
---|---|---|
visibilities | valueof string[] | 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
Target
string | ModelProperty
Parameters
None
Examples
@service
Mark this namespace as describing a service and configure service properties.
Target
Namespace
Parameters
Name | Type | Description |
---|---|---|
options | ServiceOptions | Optional configuration for the service. |
Examples
Setting service title
Setting service version
@summary
Typically a short, single-line description.
Target
unknown
Parameters
Name | Type | Description |
---|---|---|
summary | valueof string | Summary string. |
Examples
@tag
Attaches a tag to an operation, interface, or namespace. Multiple @tag
decorators can be specified to attach multiple tags to a TypeSpec element.
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
Target
ModelProperty
Parameters
Name | Type | Description |
---|---|---|
visibilities | valueof string[] | List of visibilities which apply to this property. |
Examples
@withDefaultKeyVisibility
Set the visibility of key properties in a model if not already set.
Target
Model
Parameters
Name | Type | Description |
---|---|---|
visibility | valueof string | The desired default visibility value. If a key property already has a visibility decorator then the default visibility is not applied. |
@withOptionalProperties
Returns the model with required properties removed.
Target
Model
Parameters
None
@withoutDefaultValues
Returns the model with any default values removed.
Target
Model
Parameters
None
@withoutOmittedProperties
Returns the model with the given properties omitted.
Target
Model
Parameters
Name | Type | Description |
---|---|---|
omit | string | Union | List of properties to omit |
@withPickedProperties
Returns the model with only the given properties included.
Target
Model
Parameters
Name | Type | Description |
---|---|---|
pick | string | Union | List of properties to include |
@withUpdateableProperties
Returns the model with non-updateable properties removed.
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.
Target
Model
Parameters
Name | Type | Description |
---|---|---|
visibilities | valueof string[] | List of visibilities which apply to this property. |