[Swagger Linter Migration] LatestVersionOfCommonTypesMustBeUsed

[Yuchao Yan (msyyc)]

Original Swagger linter

Rule: LatestVersionOfCommonTypesMustBeUsed

Swagger source:

• Docs: https://github.com/Azure/azure-openapi-validator/blob/main/docs/latest-version-of-common-types-must-be-used.md
• Function: https://github.com/Azure/azure-openapi-validator/blob/main/packages/rulesets/src/spectral/functions/latest-version-of-common-types-must-be-used.ts
• ARM ruleset registration: https://github.com/Azure/azure-openapi-validator/blob/main/packages/rulesets/src/spectral/az-arm.ts

Original checks:

• Runs on every Swagger $ref value via given: "$..['$ref']" in the ARM ruleset.
• Ignores null refs and refs that do not match /common-types/resource-management/v\d+/\w+.json#.
• Extracts the referenced common-types version and file name from the $ref path.
• Uses isLatestCommonTypesVersionForFile and LATEST_VERSION_BY_COMMON_TYPES_FILENAME to decide whether that file is referenced through the latest known common-types version.
• Emits one warning at the $ref path when the referenced version differs from the latest map entry.

How the Swagger linter works

The Swagger validator is a Spectral function over emitted OpenAPI 2.0 documents. It does not understand TypeSpec symbols, ARM service namespaces, @armCommonTypesVersion, or version projections. Instead, it scans each emitted $ref string, filters to ARM common-types references under /common-types/resource-management/v*/, extracts {version, file}, and compares the extracted version with a hard-coded filename-to-latest-version map.

That string-level traversal means Swagger diagnostic locations are emitted $ref paths and raw diagnostic cardinality is tied to every repeated emitted occurrence. It also means the validator can be stale when the hard-coded map is stale. The lintdiff evidence records known stale-map false positives for valid v6 networksecurityperimeter.json and managedidentitywithdelegation.json references that the validator still maps to v5; the promoted rule intentionally does not copy those stale data defects.

Source TypeSpec lintdiff rule

Source lintdiff rule id: LatestVersionOfCommonTypesMustBeUsed

Local rule name: latest-version-of-common-types-must-be-used

Official TypeSpec rule name: use-latest-version-of-common-types (renamed during promotion to follow TypeSpec linter naming conventions)

Source branch: feature/lintdiff-latest-version-common-types

Source commit inspected: be310817b95a8c2fba64b7906e23624ec38efab0

Source worktree: C:\dev\worktrees\lintdiff-latest-version-common-types-source

Source rule: https://github.com/Azure/typespec-azure/blob/feature/lintdiff-latest-version-common-types/packages/typespec-lintdiff/src/rules/latest-version-of-common-types-must-be-used.ts

The source worktree was clean, with no uncommitted rule changes. The user-marked done lintdiff source rule was not modified during promotion.

Destination analysis

Selected package: @azure-tools/typespec-azure-resource-manager.

@azure-tools/typespec-azure-core was considered but rejected because this rule is ARM-specific and depends on ARM-only concepts and helpers. The validator metadata marks applicability as ARM with source arm; the fixture rule docs say it applies to Resource Manager; the implementation checks ARM provider namespaces, reads effective @armCommonTypesVersion, resolves ARM common type references, and imports ARM helpers such as getArmCommonTypesVersion, getArmCommonTypesVersions, isArmCommonType, and getArmCommonTypeOpenAPIRef. Moving this to core would require rewriting away ARM package dependencies and would violate the dependency direction that core must not depend on resource-manager.

The existing official ARM arm-common-types-version rule is related but not equivalent: it requires specifying a common-types version, while this promoted rule requires selecting the latest common-types version and catches latest-version APIs that still emit legacy common-type symbols.

The rule is explicitly listed in @azure-tools/typespec-azure-rulesets/resource-manager but disabled by default for staged rollout. Existing Azure service specs and repo samples still select older ARM common-types versions, so enabling it immediately would convert those existing warnings into CI failures. Teams can opt in directly, and the default ruleset can be flipped after specs are updated or intentionally suppressed.

How the promoted TypeSpec linter works

The promoted rule runs once at program root and visits TypeSpec services registered as ARM provider namespaces. It discovers the latest available ARM common-types version from Azure.ResourceManager.CommonTypes.Versions, compares the effective @armCommonTypesVersion on the service namespace or each version enum member, and reports older selections on the namespace or enum-member target.

When an API version already selects the latest common-types version, it projects versioned services with the same versioning mutators used by the emitter, resolves HTTP operations from the projected service, and walks operation parameters, request bodies, and response bodies. It uses HTTP metadata visibility (resolveRequestVisibility, Visibility.Read, and createMetadataInfo().isPayloadProperty) so properties excluded from the emitted payload are not false positives. For each reachable ARM common type, it asks getArmCommonTypeOpenAPIRef which common-types file would be emitted for that service/version and warns when that resolved reference is older than the latest version.

Diagnostics are deduplicated per target plus resolved reference identity, so repeated traversal of the same target does not spam while two distinct operations producing the same legacy reference each get actionable diagnostics. This intentionally differs from the Swagger validator's emitted-$ref occurrence count while preserving project-level behavior.

Fixture-to-native test mapping

Source fixtures are linked from the lintdiff source branch and converted into native vitest coverage in packages/typespec-azure-resource-manager/test/rules/use-latest-version-of-common-types.test.ts:

• older-common-types -> emits when a versioned ARM service inherits namespace-level v3.
• latest-common-types -> valid when namespace-level selection is latest v6.
• version-override-older-common-types -> emits when a version enum member overrides a latest namespace selection back to v3.
• version-override-latest-common-types -> valid when a version enum member overrides an older namespace selection to latest v6.
• legacy-location-parameter -> emits when a latest-version API still uses legacy LocationParameter resolving to v5/types.json.
• legacy-managed-identity -> emits for legacy managed identity definitions resolving to v4/managedidentity.json.
• versioned-legacy-property -> emits only for the projected API version where the added legacy property exists.
• repeated-legacy-reference -> emits once per distinct operation producing the same legacy reference.
• payload-visibility-excludes-legacy -> remains valid when legacy common types are excluded by request/response payload visibility or nested metadata handling.

The native tests use direct TypeSpec snippets and expected diagnostics rather than copying lintdiff snapshots.

Migration evidence

Detailed migration evidence is in the source rule's migration report: https://github.com/Azure/typespec-azure/blob/feature/lintdiff-latest-version-common-types/packages/typespec-lintdiff/test/fixtures/LatestVersionOfCommonTypesMustBeUsed/migration.md

That report records the focused fixture tests, full-corpus comparison, one-sided project explanations, known validator stale-map behavior, compile failures, and remaining uncertainty. In short: after aligning selected API population and excluding known stale validator-map false positives, both sides fire in the same 384 successfully compiled projects, with raw diagnostic counts intentionally different because Swagger reports emitted $ref occurrences while TypeSpec reports semantic source usages and version selections.

Validation

• pnpm --filter @azure-tools/typespec-azure-resource-manager exec vitest run test/rules/use-latest-version-of-common-types.test.ts
• pnpm -r --filter "@azure-tools/typespec-azure-resource-manager..." build
• pnpm --filter @azure-tools/typespec-azure-resource-manager build
• pnpm --filter @azure-tools/typespec-azure-resource-manager lint
• pnpm --filter @azure-tools/typespec-azure-resource-manager regen-docs
• pnpm --filter @azure-tools/typespec-azure-rulesets build
• pnpm --filter @azure-tools/typespec-azure-rulesets test
• pnpm --filter @azure-tools/typespec-azure-playground-website exec vitest run test/validate-samples.test.ts
• pnpm --filter @azure-tools/typespec-samples exec vitest run test/samples.test.ts -t "legacy/legacy-operations"
• pnpm --filter @azure-tools/typespec-azure-resource-manager test
• Focused code review of promotion diff: no blocking findings.
• git diff --check

Validation blocker

pnpm validate:pr was attempted on the final branch but hung after printing only Branch is up to date for more than 13 minutes. The process was idle and was stopped. The narrower promotion validations above completed successfully.

Promotion sync policy

If review finds a semantic gap after promotion, this PR should be blocked until the user explicitly reopens lintdiff rule repair. The done lintdiff source rule was treated as immutable during promotion and was not edited here.

[github-actions]

All changed packages have been documented.

• ✅ @azure-tools/typespec-azure-resource-manager
• ✅ @azure-tools/typespec-azure-rulesets

Show changes

@azure-tools/typespec-azure-resource-manager - feature ✏️

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.

@azure-tools/typespec-azure-rulesets - feature ✏️

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.

[github-actions]

📦 Package size report

1 package changed size, +1.64 KB (+0.0%) packed overall.

Package	Packed (base → head)	Δ Packed	Unpacked (base → head)	Δ Unpacked
@azure-tools/typespec-client-generator-core	227.76 KB → 229.25 KB	+1.49 KB (+0.7%) 🔴	1.23 MB → 1.23 MB	+3.31 KB (+0.3%)

12 package(s) with no notable change

Package	Packed (base → head)	Δ Packed	Unpacked (base → head)	Δ Unpacked
@azure-tools/typespec-azure-rulesets	5.16 KB → 5.25 KB	+86 B (+1.6%)	32.09 KB → 32.43 KB	+349 B (+1.1%)
@azure-tools/typespec-azure-resource-manager	176.29 KB → 176.36 KB	+78 B (+0.0%)	1.07 MB → 1.07 MB	+665 B (+0.1%)
@azure-tools/typespec-java	13.51 MB → 13.51 MB	-57 B (-0.0%)	15.03 MB → 15.03 MB	+65 B (+0.0%)
@azure-tools/typespec-go	258.42 KB → 258.44 KB	+29 B (+0.0%)	1.32 MB → 1.32 MB	+95 B (+0.0%)
@azure-tools/typespec-python	42.20 KB → 42.22 KB	+20 B (+0.0%)	164.85 KB → 164.91 KB	+65 B (+0.0%)
@azure-tools/typespec-ts	527.17 KB → 527.17 KB	-2 B (-0.0%)	2.54 MB → 2.54 MB	—
@azure-tools/azure-http-specs	146.63 KB → 146.63 KB	—	1.16 MB → 1.16 MB	—
@azure-tools/typespec-autorest	80.93 KB → 80.93 KB	—	395.06 KB → 395.06 KB	—
@azure-tools/typespec-autorest-canonical	7.42 KB → 7.42 KB	—	26.00 KB → 26.00 KB	—
@azure-tools/typespec-azure-core	129.43 KB → 129.43 KB	—	702.77 KB → 702.77 KB	—
@azure-tools/typespec-azure-portal-core	42.40 KB → 42.40 KB	—	192.91 KB → 192.91 KB	—
@azure-tools/typespec-metadata	15.91 KB → 15.91 KB	—	62.26 KB → 62.26 KB	—

_{Packed = gzipped .tgz published to npm. Unpacked = total extracted size. 🆕 added, 🗑️ removed. Packages from the core/ submodule are not included.
🔴 grew · 🟢 shrank — only changes of at least 512 B and 0.5% are marked.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@azure-tools/typespec-azure-resource-manager@5271

npm i https://pkg.pr.new/@azure-tools/typespec-azure-rulesets@5271

commit: 09df69b

[azure-sdk-automation]

You can try these changes here

🛝 Playground	🌐 Website