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 TypeSpec. 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. The generated Swagger files can be found in the common-types/openapi directory.

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

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.

   @@armCommonDefinition(ExtensionResource,
     "ProxyResource",
     Azure.ResourceManager.CommonTypes.Versions.v6
   );

3. If it is a completely new version, add the version to versions.tsp)
4. Generate the Swagger updates by running:

   cd typespec-azure\packages\samples\common-types
   pnpm regen-common-types

5. Generate the documentation

   pnpm gen-docs

Create a new common type

Example of a pull request

1. Create a new file in the common-types folder with your common type name, e.g., managed-identity-with-delegation.tsp.

2. 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.

3. Create a new reference file in the common-types folder with the common type name and the -ref suffix, e.g., managed-identity-with-delegation-ref.tsp

4. Edit the -ref file:

   • Start by importing the common type TypeSpec file.

     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.

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

5. Add the common-type file to common-types.tsp

6. Create an equivalent file of the common type in samples/common-types/src (managed-identity-with-delegation.tsp)

7. 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";

8. Indicate that you want to emit the common types Swagger by updating gen.ts), adding a line like the following:

   await emitCommonTypesSwagger("managed-identity-with-delegation");

9. Generate the Swagger updates by running:

   cd typespec-azure\packages\samples\common-types
   pnpm regen-common-types

10. Finally, generate the documentation:

    pnpm gen-docs