[Swagger Linter Migration] LatestVersionOfCommonTypesMustBeUsed -> arm-common-types-version

.chronus/changes/promote-latest-version-common-types-2026-08-20-14-00-00.md

@@ -0,0 +1,11 @@
+---
+changeKind: feature
+packages:
+  - "@azure-tools/typespec-azure-resource-manager"
+---
+
+Extend `arm-common-types-version` to warn when an ARM service or API version selects an older common-types version, while preserving the existing warning for missing explicit version configuration.
+
+Latest-version warnings are now active wherever this existing rule is enabled, including the resource-manager ruleset. Update `@armCommonTypesVersion` to the latest version in `Azure.ResourceManager.CommonTypes.Versions`, or suppress `@azure-tools/typespec-azure-resource-manager/arm-common-types-version` when an older version is required for compatibility.
+
+The rule checks effective version selections only.

packages/samples/specs/resource-manager/legacy/legacy-operations/main.tsp

@@ -19,6 +19,7 @@ namespace Microsoft.ContosoProviderHub;
 /** Contoso API versions */
 enum Versions {
   /** 2021-10-01-preview version */
+  #suppress "@azure-tools/typespec-azure-resource-manager/arm-common-types-version" "Preserve older common-types schemas for this grandfathered API sample."
   @armCommonTypesVersion(Azure.ResourceManager.CommonTypes.Versions.v5)
   @Azure.Core.previewVersion
   `2021-10-01-preview`,

packages/samples/specs/resource-manager/legacy/managed-identity/main.tsp

@@ -19,6 +19,7 @@ namespace Microsoft.UpdateTests;
 /** UpdateTests API versions */
 enum Versions {
   /** 2023-03-01-preview version */
+  #suppress "@azure-tools/typespec-azure-resource-manager/arm-common-types-version" "This sample intentionally mixes v3 common types with the legacy v4 managed identity."
   @armCommonTypesVersion(Azure.ResourceManager.CommonTypes.Versions.v3)
   @previewVersion
   `2023-03-01-preview`,

packages/samples/specs/resource-manager/legacy/non-standard-properties/main.tsp

@@ -16,6 +16,7 @@ namespace Microsoft.ContosoProviderHub;
 /** Contoso API versions */
 enum Versions {
   /** 2021-10-01-preview version */
+  #suppress "@azure-tools/typespec-azure-resource-manager/arm-common-types-version" "Preserve older common-types schemas for this grandfathered API sample."
   @armCommonTypesVersion(Azure.ResourceManager.CommonTypes.Versions.v5)
   @Azure.Core.previewVersion
   `2021-10-01-preview`,

packages/samples/specs/resource-manager/legacy/nsp/main.tsp

@@ -17,6 +17,7 @@ namespace Microsoft.ContosoProviderHub;
 /** Contoso API versions */
 enum Versions {
   /** 2025-11-19-preview version */
+  #suppress "@azure-tools/typespec-azure-resource-manager/arm-common-types-version" "Preserve older common-types schemas for this grandfathered API sample."
   @armCommonTypesVersion(Azure.ResourceManager.CommonTypes.Versions.v5)
   @previewVersion
   `2025-11-19-preview`,

packages/samples/specs/resource-manager/legacy/optional-body/main.tsp

@@ -13,6 +13,7 @@ namespace Microsoft.OptionalBody;
 interface Operations extends Azure.ResourceManager.Operations {}
 
 enum Versions {
+  #suppress "@azure-tools/typespec-azure-resource-manager/arm-common-types-version" "Preserve older common-types schemas for this grandfathered API sample."
   @armCommonTypesVersion(Azure.ResourceManager.CommonTypes.Versions.v5)
   @Azure.Core.previewVersion
   `2025-01-01-preview`,

packages/samples/specs/resource-manager/legacy/polymorphic-resource/main.tsp

@@ -19,6 +19,7 @@ namespace Microsoft.ContosoProviderHub;
 /** Contoso API versions */
 enum Versions {
   /** 2021-10-01-preview version */
+  #suppress "@azure-tools/typespec-azure-resource-manager/arm-common-types-version" "Preserve older common-types schemas for this grandfathered API sample."
   @armCommonTypesVersion(Azure.ResourceManager.CommonTypes.Versions.v5)
   @Azure.Core.previewVersion
   `2025-10-01-preview`,

packages/samples/specs/resource-manager/legacy/private-endpoints/main.tsp

@@ -17,6 +17,7 @@ namespace Microsoft.ContosoProviderHub;
 /** Contoso API versions */
 enum Versions {
   /** 2021-10-01-preview version */
+  #suppress "@azure-tools/typespec-azure-resource-manager/arm-common-types-version" "Preserve older common-types schemas for this grandfathered API sample."
   @armCommonTypesVersion(Azure.ResourceManager.CommonTypes.Versions.v5)
   @previewVersion
   `2021-10-01-preview`,

packages/samples/specs/resource-manager/legacy/private-links/main.tsp

@@ -17,6 +17,7 @@ namespace Microsoft.ContosoProviderHub;
 /** Contoso API versions */
 enum Versions {
   /** 2021-10-01-preview version */
+  #suppress "@azure-tools/typespec-azure-resource-manager/arm-common-types-version" "Preserve older common-types schemas for this grandfathered API sample."
   @armCommonTypesVersion(Azure.ResourceManager.CommonTypes.Versions.v5)
   @previewVersion
   `2021-10-01-preview`,

packages/samples/specs/resource-manager/legacy/rename-operations/main.tsp

@@ -12,6 +12,7 @@ namespace Microsoft.RenamedOperations;
 interface Operations extends Azure.ResourceManager.Operations {}
 
 enum Versions {
+  #suppress "@azure-tools/typespec-azure-resource-manager/arm-common-types-version" "Preserve older common-types schemas for this grandfathered API sample."
   @armCommonTypesVersion(Azure.ResourceManager.CommonTypes.Versions.v5)
   @Azure.Core.previewVersion
   `2025-01-01-preview`,

packages/samples/specs/resource-manager/legacy/static-routes/main.tsp

@@ -20,6 +20,7 @@ namespace Microsoft.ContosoProviderHub;
 interface Operations extends Azure.ResourceManager.Operations {}
 
 enum Versions {
+  #suppress "@azure-tools/typespec-azure-resource-manager/arm-common-types-version" "Preserve older common-types schemas for this grandfathered API sample."
   @armCommonTypesVersion(Azure.ResourceManager.CommonTypes.Versions.v5)
   @previewVersion
   `2025-06-01-preview`,

packages/samples/specs/resource-manager/resource-common-properties/private-links/main.tsp

@@ -16,10 +16,12 @@ namespace Microsoft.PrivateLinkTest;
 
 @doc("The PrivateLinkTest service versions.")
 enum Versions {
+  #suppress "@azure-tools/typespec-azure-resource-manager/arm-common-types-version" "This sample demonstrates private-link schema compatibility across older common-types versions."
   @armCommonTypesVersion(Azure.ResourceManager.CommonTypes.Versions.v4)
   @doc("The 2023-08-01 version.")
   `2023-08-01`,
 
+  #suppress "@azure-tools/typespec-azure-resource-manager/arm-common-types-version" "This sample demonstrates private-link schema compatibility across older common-types versions."
   @armCommonTypesVersion(Azure.ResourceManager.CommonTypes.Versions.v5)
   @doc("The 2023-11-01-preview version.")
   @Azure.Core.previewVersion

packages/typespec-azure-resource-manager/README.md

@@ -35,7 +35,7 @@ Available ruleSets:
 | [`@azure-tools/typespec-azure-resource-manager/arm-no-path-casing-conflicts`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-no-path-casing-conflicts)                           | Operation paths must be unique when compared case-insensitively.                                                                                                                                                                                      |
 | [`@azure-tools/typespec-azure-resource-manager/scope-path-segment-casing`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/scope-path-segment-casing)                                 | ARM paths must use the canonical subscriptions and resourceGroups segment casing.                                                                                                                                                                     |
 | [`@azure-tools/typespec-azure-resource-manager/no-override-props`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/no-override-props)                                                 | Disallow redefining properties already defined in a base type.                                                                                                                                                                                        |
-| [`@azure-tools/typespec-azure-resource-manager/arm-common-types-version`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-common-types-version)                                   | Specify the ARM common-types version using @armCommonTypesVersion.                                                                                                                                                                                    |
+| [`@azure-tools/typespec-azure-resource-manager/arm-common-types-version`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-common-types-version)                                   | Specify the latest ARM common-types version using @armCommonTypesVersion.                                                                                                                                                                             |
 | [`@azure-tools/typespec-azure-resource-manager/arm-delete-operation-response-codes`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-delete-operation-response-codes)             | Ensure delete operations have the appropriate status codes.                                                                                                                                                                                           |
 | [`@azure-tools/typespec-azure-resource-manager/arm-put-operation-response-codes`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-put-operation-response-codes)                   | Ensure put operations have the appropriate status codes.                                                                                                                                                                                              |
 | [`@azure-tools/typespec-azure-resource-manager/arm-post-operation-response-codes`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-post-operation-response-codes)                 | Ensure post operations have the appropriate status codes.                                                                                                                                                                                             |

packages/typespec-azure-resource-manager/src/rules/arm-common-types-version.md

@@ -1,10 +1,20 @@
-If the same common types version is used across all service versions, this decorator should be applied either on the service namespace or on each version enum member. If the common types version is updated in later versions, the decorator should appear on each version enum member.
+ARM services should explicitly select the latest version in
+`Azure.ResourceManager.CommonTypes.Versions` using `@armCommonTypesVersion`.
+Apply the decorator to the service namespace when all API versions use the same
+common-types version. A decorator on an API version enum member overrides the
+namespace selection for that API version.
+
+The rule warns when explicit version configuration is missing or when an
+effective selection is older than the latest available version. It checks
+version selections, not individual legacy type usages.
 
 ## Impact
 
 - **Area:** API, SDK
 
-Indicates common-types are not being used, which normally surfaces as other violations too.
+Missing or outdated common-types selections can leave an API and its generated
+SDKs using older shared schemas and parameters. Latest-version warnings are
+enabled wherever this rule is enabled, including the resource-manager ruleset.
 
 ## ❌ Incorrect
 
@@ -13,33 +23,47 @@ Indicates common-types are not being used, which normally surfaces as other viol
 namespace Microsoft.Contoso;
 ```
 
-## ✅ Correct
-
-Apply `@armCommonTypesVersion` on the namespace:
+An explicit older selection also produces a warning:
 
 ```tsp
 @armProviderNamespace
-@armCommonTypesVersion(Azure.ResourceManager.CommonTypes.Versions.v5)
+@armCommonTypesVersion(Azure.ResourceManager.CommonTypes.Versions.v3)
 namespace Microsoft.Contoso;
 ```
 
-## ✅ Correct (per version)
+## ✅ Correct
 
-Apply `@armCommonTypesVersion` on each version enum member:
+Select the latest version on the service namespace:
 
 ```tsp
 @armProviderNamespace
+@armCommonTypesVersion(Azure.ResourceManager.CommonTypes.Versions.v6)
 namespace Microsoft.Contoso;
+```
 
-enum Versions {
-  @armCommonTypesVersion(Azure.ResourceManager.CommonTypes.Versions.v4)
-  v1,
+Alternatively, apply `@armCommonTypesVersion` to every API version enum member
+instead of the namespace. Every effective selection must use the latest version
+to satisfy this rule.
 
-  @armCommonTypesVersion(Azure.ResourceManager.CommonTypes.Versions.v5)
-  v2,
-}
-```
+As of August 2026, `v6` was the latest ARM common-types version.
+Newer versions may exist; check `Azure.ResourceManager.CommonTypes.Versions`
+before updating a service.
+
+## LintDiff Equivalent
+
+This rule covers the version-selection guidance of
+[`LatestVersionOfCommonTypesMustBeUsed`](https://github.com/Azure/azure-openapi-validator/blob/main/docs/latest-version-of-common-types-must-be-used.md).
+Unlike the OpenAPI rule, it does not inspect emitted common-type references.
 
 ## Suppression
 
-Suppress only if no common-types are ever used and that is valid; otherwise associate a common-types version with each version in the Versions enum.
+Prefer updating `@armCommonTypesVersion` to the latest version. Suppress only
+when an older version is required for compatibility and the API and SDK impact
+has been accepted, or when no common-types are used and omitting the selection
+is intentional.
+
+Place `#suppress "@azure-tools/typespec-azure-resource-manager/arm-common-types-version" "Compatibility justification"`
+above the service namespace for missing configuration or an unversioned
+selection, or above the affected API version enum member for a versioned
+selection. Suppressing the rule also suppresses its missing-configuration check
+within that scope.

packages/typespec-azure-resource-manager/src/rules/arm-common-types-version.ts

@@ -1,32 +1,40 @@
-import { type Program, type SemanticNodeListener, createRule, fileRef } from "@typespec/compiler";
-import { getAllHttpServices } from "@typespec/http";
+import {
+  type Program,
+  type SemanticNodeListener,
+  createRule,
+  fileRef,
+  listServices,
+  paramMessage,
+} from "@typespec/compiler";
 import { getVersion } from "@typespec/versioning";
+import { getArmCommonTypesVersion, getArmCommonTypesVersions } from "../common-types.js";
 import { getArmProviderNamespace } from "../namespace.js";
 
 /**
- * The @armCommonTypesVersion decorator should be used to set the ARM
- * common-types version used by the service.
+ * The @armCommonTypesVersion decorator should select the latest ARM common-types version.
  */
 export const armCommonTypesVersionRule = createRule({
   name: "arm-common-types-version",
   docs: fileRef.fromPackageRoot("src/rules/arm-common-types-version.md"),
   severity: "warning",
-  description: "Specify the ARM common-types version using @armCommonTypesVersion.",
+  description: "Specify the latest ARM common-types version using @armCommonTypesVersion.",
   url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-common-types-version",
   messages: {
     default:
       "Specify the ARM common-types version using the @armCommonTypesVersion decorator on the service namespace or on each version of the service version enum.",
+    outdated: paramMessage`Use the latest ARM common-types version '${"latestVersion"}' instead of '${"currentVersion"}'.`,
   },
   create(context): SemanticNodeListener {
     return {
       root: (program: Program) => {
-        const [services, _] = getAllHttpServices(program);
-        for (const service of services) {
-          if (!getArmProviderNamespace(program, service.namespace)) {
+        // The common-types registry stores versions newest first.
+        const latestVersion = getArmCommonTypesVersions(program)?.allVersions[0]?.name;
+        for (const { type: namespace } of listServices(program)) {
+          if (!getArmProviderNamespace(program, namespace)) {
             continue;
           }
 
-          const versionMap = getVersion(program, service.namespace);
+          const versionMap = getVersion(program, namespace);
           // If the namespace is versioned and not all versions have the
           // common-types version and if the service namespace doesn't have a
           // common-types version, raise a diagnostic.
@@ -42,13 +50,32 @@ export const armCommonTypesVersionRule = createRule({
                     ),
                 )
             ) &&
-            !service.namespace.decorators.find(
-              (x) => x.definition?.name === "@armCommonTypesVersion",
-            )
+            !namespace.decorators.find((x) => x.definition?.name === "@armCommonTypesVersion")
           ) {
             context.reportDiagnostic({
-              target: service.namespace,
+              messageId: "default",
+              target: namespace,
             });
+            continue;
+          }
+
+          if (latestVersion === undefined) {
+            continue;
+          }
+
+          const namespaceVersion = getArmCommonTypesVersion(program, namespace);
+          const targets = versionMap
+            ? versionMap.getVersions().map((version) => version.enumMember)
+            : [namespace];
+          for (const target of targets) {
+            const currentVersion = getArmCommonTypesVersion(program, target) ?? namespaceVersion;
+            if (currentVersion !== undefined && currentVersion !== latestVersion) {
+              context.reportDiagnostic({
+                messageId: "outdated",
+                target,
+                format: { latestVersion, currentVersion },
+              });
+            }
           }
         }
       },