[Swagger Linter Migration] LatestVersionOfCommonTypesMustBeUsed

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

@@ -0,0 +1,8 @@
+---
+changeKind: feature
+packages:
+  - "@azure-tools/typespec-azure-resource-manager"
+  - "@azure-tools/typespec-azure-rulesets"
+---
+
+Add an ARM lint rule that warns when services select or emit older ARM common-types versions instead of the latest available common-types version.

packages/typespec-azure-resource-manager/src/linter.ts

@@ -25,6 +25,7 @@ import { armResourceProvisioningStateRule } from "./rules/arm-resource-provision
 import { beyondNestingRule } from "./rules/beyond-nesting-levels.js";
 import { envelopePropertiesRules } from "./rules/envelope-properties.js";
 import { improperSubscriptionListOperationRule } from "./rules/improper-subscription-list-operation.js";
+import { latestVersionOfCommonTypesMustBeUsedRule } from "./rules/latest-version-of-common-types-must-be-used.js";
 import { lroLocationHeaderRule } from "./rules/lro-location-header.js";
 import { missingXmsIdentifiersRule } from "./rules/missing-x-ms-identifiers.js";
 import { noEmptyModel } from "./rules/no-empty-model.js";
@@ -78,6 +79,7 @@ const rules = [
   armResourceInvalidActionVerbRule,
   improperSubscriptionListOperationRule,
   lroLocationHeaderRule,
+  latestVersionOfCommonTypesMustBeUsedRule,
   missingXmsIdentifiersRule,
   noResponseBodyRule,
   operationsInterfaceMissingRule,

packages/typespec-azure-resource-manager/src/rules/latest-version-of-common-types-must-be-used.md

@@ -0,0 +1,108 @@
+ARM services should use the latest ARM common-types version available in
+`Azure.ResourceManager.CommonTypes.Versions`. This keeps generated Swagger and
+SDKs aligned with the current ARM common schemas.
+
+The rule checks the effective `@armCommonTypesVersion` on each ARM service or
+service version. When the selected version is current, it also checks common
+types reachable from HTTP operation parameters and payloads so older legacy
+symbols are not emitted through an otherwise current API version.
+
+## Impact
+
+- **Area:** API, SDK
+
+Older ARM common-types versions can emit stale shared schemas or parameters into
+Swagger even when newer definitions are available.
+
+## Incorrect
+
+```tsp
+@armProviderNamespace
+@service(#{ title: "Contoso" })
+@versioned(Versions)
+@armCommonTypesVersion(Azure.ResourceManager.CommonTypes.Versions.v3)
+namespace Microsoft.Contoso;
+
+enum Versions {
+  @useDependency(Azure.ResourceManager.CommonTypes.Versions.v3)
+  v2024_01_01: "2024-01-01",
+}
+```
+
+## Correct
+
+```tsp
+@armProviderNamespace
+@service(#{ title: "Contoso" })
+@versioned(Versions)
+@armCommonTypesVersion(Azure.ResourceManager.CommonTypes.Versions.v6)
+namespace Microsoft.Contoso;
+
+enum Versions {
+  @useDependency(Azure.ResourceManager.CommonTypes.Versions.v6)
+  v2024_01_01: "2024-01-01",
+}
+```
+
+## Incorrect
+
+This service selects the latest common-types version but still uses a legacy
+common type that resolves to an older common-types file.
+
+```tsp
+@armProviderNamespace
+@service(#{ title: "Contoso" })
+@versioned(Versions)
+@armCommonTypesVersion(Azure.ResourceManager.CommonTypes.Versions.v6)
+namespace Microsoft.Contoso;
+
+enum Versions {
+  @useDependency(Azure.ResourceManager.CommonTypes.Versions.v6)
+  v2024_01_01: "2024-01-01",
+}
+
+@route("/identity")
+@get
+op getIdentity(): Azure.ResourceManager.Legacy.ManagedServiceIdentityV4;
+```
+
+## Correct
+
+Use a common type supported by the selected latest common-types version, or
+remove the legacy reference when the API shape no longer needs it.
+
+```tsp
+@armProviderNamespace
+@service(#{ title: "Contoso" })
+@versioned(Versions)
+@armCommonTypesVersion(Azure.ResourceManager.CommonTypes.Versions.v6)
+namespace Microsoft.Contoso;
+
+enum Versions {
+  @useDependency(Azure.ResourceManager.CommonTypes.Versions.v6)
+  v2024_01_01: "2024-01-01",
+}
+
+model Widget is TrackedResource<WidgetProperties> {
+  ...ManagedServiceIdentityProperty;
+
+  @key("widgetName")
+  @segment("widgets")
+  @path
+  name: string;
+}
+
+model WidgetProperties {
+  description?: string;
+}
+
+@route("/identity")
+@get
+op getIdentity(): Widget;
+```
+
+## Suppression
+
+Suppress only when an API must intentionally emit an older ARM common-types
+schema for compatibility and the service team has accepted the SDK and Swagger
+impact.