typespec-azure-resource-manager

@azure-tools/typespec-azure-resource-manager

TypeSpec Azure Resource Manager library

Install

npm install @azure-tools/typespec-azure-resource-manager

Usage

Add the following in tspconfig.yaml:

linter:
  extends:
    - "@azure-tools/typespec-azure-resource-manager/all"

RuleSets

Available ruleSets:

• @azure-tools/typespec-azure-resource-manager/all

Rules

Name	Description
@azure-tools/typespec-azure-resource-manager/arm-agent-base-type-child-resources	Resources decorated with @azureBaseType for the Agent base type must have both a Conversation and a Response child resource.
@azure-tools/typespec-azure-resource-manager/arm-agent-base-type-lifecycle-operations	Conversation and Response child resources of an Agent must define create, read, update, and delete lifecycle operations.
@azure-tools/typespec-azure-resource-manager/arm-no-record	Don't use Record types for ARM resources.
@azure-tools/typespec-azure-resource-manager/arm-no-path-casing-conflicts	Operation paths must be unique when compared case-insensitively.
@azure-tools/typespec-azure-resource-manager/no-override-props	Disallow redefining properties already defined in a base type.
@azure-tools/typespec-azure-resource-manager/arm-common-types-version	Specify the ARM common-types version using @armCommonTypesVersion.
@azure-tools/typespec-azure-resource-manager/arm-delete-operation-response-codes	Ensure delete operations have the appropriate status codes.
@azure-tools/typespec-azure-resource-manager/arm-put-operation-response-codes	Ensure put operations have the appropriate status codes.
@azure-tools/typespec-azure-resource-manager/arm-post-operation-response-codes	Ensure post operations have the appropriate status codes.
@azure-tools/typespec-azure-resource-manager/arm-resource-action-no-segment	@armResourceAction should not be used with @segment.
@azure-tools/typespec-azure-resource-manager/arm-resource-duplicate-property	Warn about duplicate properties in resources.
@azure-tools/typespec-azure-resource-manager/arm-resource-invalid-envelope-property	Check for invalid resource envelope properties.
@azure-tools/typespec-azure-resource-manager/arm-resource-invalid-version-format	Check for valid versions.
@azure-tools/typespec-azure-resource-manager/arm-resource-key-invalid-chars	Arm resource key must contain only alphanumeric characters.
@azure-tools/typespec-azure-resource-manager/arm-resource-name-pattern	The resource name parameter should be defined with a 'pattern' restriction.
@azure-tools/typespec-azure-resource-manager/arm-resource-operation-response	[RPC 008]: PUT, GET, PATCH & LIST must return the same resource schema.
@azure-tools/typespec-azure-resource-manager/arm-resource-path-segment-invalid-chars	Arm resource name must contain only alphanumeric characters.
@azure-tools/typespec-azure-resource-manager/arm-resource-provisioning-state	Check for properly configured provisioningState property.
@azure-tools/typespec-azure-resource-manager/version-progression	Validate that ARM service versions all use unique dates and are declared in strictly increasing chronological order.
@azure-tools/typespec-azure-resource-manager/arm-custom-resource-no-key	Validate that custom resource contains a key property.
@azure-tools/typespec-azure-resource-manager/arm-custom-resource-usage-discourage	Verify the usage of @customAzureResource decorator.
@azure-tools/typespec-azure-resource-manager/beyond-nesting-levels	Tracked Resources must use 3 or fewer levels of nesting.
@azure-tools/typespec-azure-resource-manager/arm-resource-operation	Validate ARM Resource operations.
@azure-tools/typespec-azure-resource-manager/no-resource-delete-operation	Check for resources that must have a delete operation.
@azure-tools/typespec-azure-resource-manager/empty-updateable-properties	Should have updateable properties.
@azure-tools/typespec-azure-resource-manager/arm-resource-interface-requires-decorator	Each resource interface must have an @armResourceOperations decorator.
@azure-tools/typespec-azure-resource-manager/arm-resource-invalid-action-verb	Actions must be HTTP Post or Get operations.
@azure-tools/typespec-azure-resource-manager/improper-subscription-list-operation	Tenant and Extension resources should not define a list by subscription operation.
@azure-tools/typespec-azure-resource-manager/lro-location-header	A 202 response should include a Location response header.
@azure-tools/typespec-azure-resource-manager/missing-x-ms-identifiers	Array properties should describe their identifying properties with x-ms-identifiers. Decorate the property with @OpenAPI.extension("x-ms-identifiers", #[id-prop]) where "id-prop" is a list of the names of identifying properties in the item type.
@azure-tools/typespec-azure-resource-manager/no-response-body	Check that the body is empty for 202 and 204 responses, and not empty for other success (2xx) responses.
@azure-tools/typespec-azure-resource-manager/missing-operations-endpoint	Check for missing Operations interface.
@azure-tools/typespec-azure-resource-manager/patch-envelope	Patch envelope properties should match the resource properties.
@azure-tools/typespec-azure-resource-manager/arm-resource-patch	Validate ARM PATCH operations.
@azure-tools/typespec-azure-resource-manager/resource-name	Check the resource name.
@azure-tools/typespec-azure-resource-manager/retry-after	Check if retry-after header appears in response body.
@azure-tools/typespec-azure-resource-manager/unsupported-type	Check for unsupported ARM types.
@azure-tools/typespec-azure-resource-manager/secret-prop	RPC-v1-13: Check that property with names indicating sensitive information(e.g. contains auth, password, token, secret, etc.) are marked with @secret decorator.
@azure-tools/typespec-azure-resource-manager/no-empty-model	ARM Properties with type:object that don't reference a model definition are not allowed. ARM doesn't allow generic type definitions as this leads to bad customer experience.

Decorators

Azure.ResourceManager

• @armCommonTypesVersion
• @armLibraryNamespace
• @armProviderNamespace
• @armProviderNameValue
• @armResourceAction
• @armResourceCheckExistence
• @armResourceCollectionAction
• @armResourceCreateOrUpdate
• @armResourceDelete
• @armResourceList
• @armResourceOperations
• @armResourceRead
• @armResourceUpdate
• @armVirtualResource
• @extensionResource
• @identifiers
• @locationResource
• @resourceBaseType
• @resourceGroupResource
• @singleton
• @subscriptionResource
• @tenantResource
• @useLibraryNamespace

@armCommonTypesVersion

This decorator is used either on a namespace or a version enum value to indicate the version of the Azure Resource Manager common-types to use for refs in emitted Swagger files.

@Azure.ResourceManager.armCommonTypesVersion(version: valueof string | EnumMember)

Target

Namespace | EnumMember

Parameters

Name	Type	Description
version	valueof string | EnumMember	The Azure.ResourceManager.CommonTypes.Versions for the desired common-types version or an equivalent string value like "v5".

@armLibraryNamespace

@armLibraryNamespace designates a namespace as containing Azure Resource Manager Provider information. This is used for library namespaces that define reusable ARM resource types that can be shared across multiple provider specifications.

@Azure.ResourceManager.armLibraryNamespace

Target

Namespace

Parameters

None

Examples

@armLibraryNamespace
namespace Microsoft.Contoso;

@armProviderNamespace

@armProviderNamespace sets the Azure Resource Manager provider name. It will default to use the Namespace element value unless an override value is specified.

@Azure.ResourceManager.armProviderNamespace(providerNamespace?: valueof string)

Target

Namespace

Parameters

Name	Type	Description
providerNamespace	valueof string	Provider namespace

Examples

@armProviderNamespace
namespace Microsoft.Contoso;

@armProviderNamespace("Microsoft.Contoso")
namespace Microsoft.ContosoService;

@armProviderNameValue

@armProviderNameValue sets the provider namespace value on operations. It is used internally to inject the correct provider namespace path segment for resource operations in auto-generated routes.

@Azure.ResourceManager.armProviderNameValue

Target

Operation

Parameters

None

@armResourceAction

Marks the operation as a custom action on a specific Azure Resource Manager resource type. This decorator associates a POST action operation with its resource, identifying the semantics of the operation as a resource action over a specific resource for documentation, resource validation, and use by downstream emitters.

@Azure.ResourceManager.armResourceAction(resourceModel: Model, resourceName?: valueof string)

Target

Operation

Parameters

Name	Type	Description
resourceModel	Model	Resource model
resourceName	valueof string	Optional. The name of the resource. If not provided, the name of the resource model will be used.

@armResourceCheckExistence

Marks the operation as being a check existence (HEAD) operation

@Azure.ResourceManager.armResourceCheckExistence(resourceModel: Model, resourceName?: valueof string)

Target

Operation

Parameters

Name	Type	Description
resourceModel	Model	Resource model
resourceName	valueof string	Optional. The name of the resource. If not provided, the name of the resource model will be used.

@armResourceCollectionAction

Marks the operation as being a collection action that is not associated with a specific resource instance. Collection actions are operations that act on a resource collection rather than a single resource, such as checkNameAvailability or provider-level actions.

@Azure.ResourceManager.armResourceCollectionAction

Target

Operation

Parameters

None

@armResourceCreateOrUpdate

Marks the operation as a create or update (PUT) operation for a specific Azure Resource Manager resource type. This decorator identifies the semantics of the operation as a CreateOrReplace lifecycle operation over a particular resource, for use in documentation, resource validation, and downstream emitters.

@Azure.ResourceManager.armResourceCreateOrUpdate(resourceModel: Model, resourceName?: valueof string)

Target

Operation

Parameters

Name	Type	Description
resourceModel	Model	Resource model
resourceName	valueof string	Optional. The name of the resource. If not provided, the name of the resource model will be used.

@armResourceDelete

Marks the operation as a delete (DELETE) operation for a specific Azure Resource Manager resource type. This decorator identifies the operation as a Delete lifecycle operation over the resource for us in documentation, resource validation, and downstream emitters.

@Azure.ResourceManager.armResourceDelete(resourceModel: Model, resourceName?: valueof string)

Target

Operation

Parameters

Name	Type	Description
resourceModel	Model	Resource model
resourceName	valueof string	Optional. The name of the resource. If not provided, the name of the resource model will be used.

@armResourceList

Marks the operation as a list (GET collection) operation for a specific Azure Resource Manager resource type. This decorator identifies the semantics of the operation as a collection list operation over a resource type and a particular scope for documentation, resource validation, and downstream emitters.

@Azure.ResourceManager.armResourceList(resourceModel: Model, resourceName?: valueof string)

Target

Operation

Parameters

Name	Type	Description
resourceModel	Model	Resource model
resourceName	valueof string	Optional. The name of the resource. If not provided, the name of the resource model will be used.

@armResourceOperations

This decorator is used to identify interfaces containing resource operations. By default, it marks the interface with the @autoRoute decorator so that all of its contained operations will have their routes generated automatically.

The decorator also adds a @tag decorator bearing the name of the interface so that all of the operations will be grouped based on the interface name in generated clients.

The optional resourceOperationOptions parameter provides additional options. allowStaticRoutes turns off autoRout for the interface, so individual operations can choose static (@route) or automatic (@autoRoute) routing.

resourceType: Model specifies the resource type for the operations in the interface

omitTags: true: turns off the default tagging of operations in the interface, so that individual operations must be individually tagged

@Azure.ResourceManager.armResourceOperations(resourceOperationOptions?: unknown | valueof Azure.ResourceManager.ResourceOperationOptions)

Target

Interface

Parameters

Name	Type	Description
resourceOperationOptions	unknown | valueof ResourceOperationOptions	Options for routing the operations in the interface and associating them with a specific resource

@armResourceRead

Marks the operation as a read (GET) operation for a specific Azure Resource Manager resource type. This decorator identifies the semantics of the operation as a Read lifecycle operation over a particular resource, for use in documentation, resource validation, and downstream emitters.

@Azure.ResourceManager.armResourceRead(resourceModel: Model, resourceName?: valueof string)

Target

Operation

Parameters

Name	Type	Description
resourceModel	Model	Resource model
resourceName	valueof string	Optional. The name of the resource. If not provided, the name of the resource model will be used.

@armResourceUpdate

Marks the operation as an update (PATCH) operation for a specific Azure Resource Manager resource type. This decorator identifies the operation as an Update lifecycle operation over the resource for use in documentation, resource validation, and downstream emitters.

@Azure.ResourceManager.armResourceUpdate(resourceModel: Model, resourceName?: valueof string)

Target

Operation

Parameters

Name	Type	Description
resourceModel	Model	Resource model
resourceName	valueof string	Optional. The name of the resource. If not provided, the name of the resource model will be used.

@armVirtualResource

This decorator is used on Azure Resource Manager resources that are not based on Azure.ResourceManager common types. It marks a model as an ARM virtual resource, which is useful for defining the scope of resources used only as parents for child resources, or scopes for extension resources.

@Azure.ResourceManager.armVirtualResource(provider?: valueof string)

Target

Model

Parameters

Name	Type	Description
provider	valueof string	Optional. The resource provider namespace for the virtual resource.

@extensionResource

@extensionResource marks an Azure Resource Manager resource model as an Extension resource. Extension resource extends other resource types. URL path is appended to another segment {scope} which refers to another Resource URL.

{resourceUri}/providers/Microsoft.Contoso/accessPermissions

See more details on different Azure Resource Manager resource type here.

@Azure.ResourceManager.extensionResource

Target

Model

Parameters

None

@identifiers

This decorator is used to indicate the identifying properties of objects in the array, e.g. size The properties that are used as identifiers for the object needs to be provided as a list of strings.

@Azure.ResourceManager.identifiers(properties: valueof string[])

Target

ModelProperty | unknown[]

Parameters

Name	Type	Description
properties	valueof string[]	The list of properties that are used as identifiers for the object. This needs to be provided as a list of strings.

Examples

model Pet {
  @identifiers(#["size"])
  dog: Dog;
}

@locationResource

@locationResource marks an Azure Resource Manager resource model as a location based resource.

Deprecated: This decorator is deprecated. Use @parentResource with ArmLocationResource instead. See the Location Resource sample for the recommended approach.

See more details on different Azure Resource Manager resource type here.

@Azure.ResourceManager.locationResource

Target

Model

Parameters

None

@resourceBaseType

This decorator sets the base type of the given resource, indicating where in the Azure Resource Manager hierarchy the resource is located.

@Azure.ResourceManager.resourceBaseType(baseType: "Tenant" | "Subscription" | "ResourceGroup" | "Location" | "Extension")

Target

Model

Parameters

Name	Type	Description
baseType	"Tenant" | "Subscription" | "ResourceGroup" | "Location" | "Extension"	The built-in parent of the resource, this can be "Tenant", "Subscription", "ResourceGroup", "Location", or "Extension"

@resourceGroupResource

@resourceGroupResource marks an Azure Resource Manager resource model as a resource group level resource. This is the default option for Azure Resource Manager resources. It is provided for symmetry and clarity, and you typically do not need to specify it.

/subscription/{id}/resourcegroups/{rg}/providers/Microsoft.Contoso/employees

See more details on different Azure Resource Manager resource type here.

@Azure.ResourceManager.resourceGroupResource

Target

Model

Parameters

None

@singleton

@singleton marks an Azure Resource Manager resource model as a singleton resource.

Singleton resources only have a single instance with a fixed key name. .../providers/Microsoft.Contoso/monthlyReports/default

See more details on different Azure Resource Manager resource type here.

@Azure.ResourceManager.singleton(keyValue?: valueof string | "default")

Target

Model

Parameters

Name	Type	Description
keyValue	valueof string | "default"	The name of the singleton resource. Default name is "default".

@subscriptionResource

@subscriptionResource marks an Azure Resource Manager resource model as a subscription resource.

Subscription resources have REST API paths like: /subscription/{id}/providers/Microsoft.Contoso/employees

See more details on different Azure Resource Manager resource type here.

@Azure.ResourceManager.subscriptionResource

Target

Model

Parameters

None

@tenantResource

@tenantResource marks an Azure Resource Manager resource model as a Tenant resource/Root resource/Top-Level resource.

Tenant resources have REST API paths like: /provider/Microsoft.Contoso/FooResources

See more details on different Azure Resource Manager resource type here.

@Azure.ResourceManager.tenantResource

Target

Model

Parameters

None

@useLibraryNamespace

Declare the Azure Resource Manager library namespaces used in this provider. This allows sharing Azure Resource Manager resource types across specifications

@Azure.ResourceManager.useLibraryNamespace(...namespaces: Namespace[])

Target

Namespace

Parameters

Name	Type	Description
namespaces	Namespace[]	The namespaces of Azure Resource Manager libraries used in this provider

Azure.ResourceManager.BaseTypes

• @azureBaseType

@azureBaseType

@azureBaseType marks an Azure Resource Manager resource properties model as implementing a base type. Base types define structured constraints including required and optional properties that conforming resources must implement.

This decorator may be applied multiple times to indicate conformance to multiple base types. Duplicate entries are ignored.

@Azure.ResourceManager.BaseTypes.azureBaseType(baseType: valueof Azure.ResourceManager.BaseTypes.BaseTypeInfo)

Target

Model

Parameters

Name	Type	Description
baseType	valueof BaseTypeInfo	The base type specification this resource implements.

Examples

@azureBaseType(#{ baseType: "Agent", version: "2024-06-01" })
model MyAgentProperties {
  ...AgentProperties;
  ...AgentToolProperty;
  ...DefaultProvisioningStateProperty;
}

Azure.ResourceManager.Legacy

• @armExternalType
• @armOperationRoute
• @customAzureResource
• @externalTypeRef
• @feature
• @featureOptions
• @features
• @renamePathParameter

@armExternalType

Signifies that a Resource is represented using a library type in generated SDKs.

@Azure.ResourceManager.Legacy.armExternalType

Target

The model to that is an external resource Model

Parameters

None

@armOperationRoute

Signifies that an operation is an Azure Resource Manager operation and optionally associates the operation with a route template.

@Azure.ResourceManager.Legacy.armOperationRoute(route?: valueof Azure.ResourceManager.Legacy.ArmOperationOptions)

Target

The operation to associate the model with Operation

Parameters

Name	Type	Description
route	valueof ArmOperationOptions	Optional route to associate with the operation

@customAzureResource

This decorator is used on resources that do not satisfy the definition of a resource but need to be identified as such.

@Azure.ResourceManager.Legacy.customAzureResource(options?: valueof Azure.ResourceManager.Legacy.CustomResourceOptions)

Target

Model

Parameters

Name	Type	Description
options	valueof CustomResourceOptions	Options for customizing the behavior of the resource

@externalTypeRef

Specify an external reference that should be used when emitting this type.

@Azure.ResourceManager.Legacy.externalTypeRef(jsonRef: valueof string)

Target

Model | ModelProperty

Parameters

Name	Type	Description
jsonRef	valueof string	External reference(e.g. "../../common.json#/definitions/Foo")

@feature

Decorator to associate a feature with a model, interface, or namespace

@Azure.ResourceManager.Legacy.feature(featureName: EnumMember)

Target

The target to associate the feature with Model | Operation | Interface | Namespace

Parameters

Name	Type	Description
featureName	EnumMember	The feature to associate with the target

@featureOptions

Decorator to define options for a specific feature

@Azure.ResourceManager.Legacy.featureOptions(options: valueof Azure.ResourceManager.Legacy.ArmFeatureOptions)

Target

The enum member that represents the feature EnumMember

Parameters

Name	Type	Description
options	valueof ArmFeatureOptions	The options for the feature

@features

Decorator to define a set of features

@Azure.ResourceManager.Legacy.features(features: Enum)

Target

The service namespace Namespace

Parameters

Name	Type	Description
features	Enum	The enum that contains the features

@renamePathParameter

Renames a path parameter in an Azure Resource Manager operation.

@Azure.ResourceManager.Legacy.renamePathParameter(sourceParameterName: valueof string, targetParameterName: valueof string)

Target

The operation or interface to modify Operation

Parameters

Name	Type	Description
sourceParameterName	valueof string	The name of the parameter to rename
targetParameterName	valueof string	The new name for the parameter