---
title: Adding Common Types to Azure Resource Manager (ARM)
---

This guide provides detailed instructions on how to add and manage common types in Azure Resource Manager (ARM) using Common types are reusable components that can be shared across multiple ARM templates, ensuring consistency and reducing redundancy.

The TypeSpec common-types files are located in the [typespec-azure repository](https://github.com/Azure/typespec-azure/tree/main/packages/typespec-azure-resource-manager/lib/common-types). The generated Swagger files can be found in the [common-types/openapi directory](https://github.com/Azure/typespec-azure/tree/main/packages/samples/common-types/openapi).

There are two main approaches to editing common types:

1. **Creating a New Version of an Existing Common Type**: This involves updating an existing common type with new versioning information and making necessary changes.
2. **Creating a Completely New Common Type**: This involves defining a new common type from scratch and integrating it into the existing system.

Follow the steps outlined in this guide to ensure that your common types are correctly added and documented.

## Create a New Version of an Existing Common Type

[Pull Request Example](https://github.com/Azure/typespec-azure/pull/1689/files)

Creating a new version of an existing common type mostly involves editing what is already there and adding the new version of the common type.

1. Make all the necessary versioning changes in the common-type file, mostly using `@added(Versions.vX)`, `@removed(Versions.vX)`, and `@typeChangedFrom(Versions.vX)` decorators.
2. Update the common-type-ref file by adding the new version of the common type using the `@@armCommonDefinition` decorator .This needs to be done for all the definitions present in the new version, not only the newly added definitions.
   ```typespec
   @@armCommonDefinition(
     ExtensionResource,
     "ProxyResource",
     Azure.ResourceManager.CommonTypes.Versions.v6
   );
   ```
3. If it is a completely new version, add the version to [versions.tsp](https://github.com/Azure/typespec-azure/blob/main/packages/typespec-azure-resource-manager/lib/common-types/versions.tsp)
4. Generate the Swagger updates by running:
   ```bash
   cd typespec-azure\packages\samples\common-types
   pnpm regen-common-types
   ```
5. Generate the documentation
   ```bash
   pnpm gen-docs
   ```

## Create a new common type

[Example of a pull request](https://github.com/Azure/typespec-azure/pull/1505/files)

1. Create a new file in the [common-types folder](https://github.com/Azure/typespec-azure/tree/main/packages/typespec-azure-resource-manager/lib/common-types) with your common type name, e.g., `managed-identity-with-delegation.tsp`.
1. Write the common type in the `managed-identity-with-delegation.tsp` file:
   - Use the `@added(Versions.vX)` decorator in all models to specify in which version the model is added.
1. Create a new reference file in the [common-types folder](https://github.com/Azure/typespec-azure/tree/main/packages/typespec-azure-resource-manager/lib/common-types) with the common type name and the `-ref` suffix, e.g., `managed-identity-with-delegation-ref.tsp`
1. Edit the `-ref` file:
   - Start by importing the common type TypeSpec file.
     ```typespec
     import "./managed-identity-with-delegation.tsp";
     ```
   - In the `-ref` file write the reference to all the definitions you just created using the `@@armCommonDefinition(` decorator. Expose every single version in which the definition is available.

     ```typespec
     @@armCommonDefinition(
       ManagedServiceIdentityWithDelegation,
       "ManagedServiceIdentityWithDelegation",
       Azure.ResourceManager.CommonTypes.Versions.v4
     );
     @@armCommonDefinition(
       ManagedServiceIdentityWithDelegation,
       "ManagedServiceIdentityWithDelegation",
       Azure.ResourceManager.CommonTypes.Versions.v5
     );
     ```

1. Add the common-type file to [common-types.tsp](https://github.com/Azure/typespec-azure/blob/main/packages/typespec-azure-resource-manager/lib/common-types/common-types.tsp)
1. Create an equivalent file of the common type in [samples/common-types/src](https://github.com/Azure/typespec-azure/tree/main/packages/samples/common-types/src) (`managed-identity-with-delegation.tsp`)
1. In that file, import the TypeSpec file you created before: `import "../../node_modules/@azure-tools/typespec-azure-resource-manager/lib/common-types/managed-identity-with-delegation.tsp";`
1. Indicate that you want to emit the common types Swagger by updating [gen.ts](https://github.com/Azure/typespec-azure/blob/main/packages/samples/common-types/gen.ts)), adding a line like the following:
   ```typespec
   await emitCommonTypesSwagger("managed-identity-with-delegation");
   ```
1. Generate the Swagger updates by running:
   ```bash
   cd typespec-azure\packages\samples\common-types
   pnpm regen-common-types
   ```
1. Finally, generate the documentation:
   ```bash
   pnpm gen-docs
   ```
