[Swagger Linter Migration] LatestVersionOfCommonTypesMustBeUsed (origin)

[Yuchao Yan (msyyc)]

Original Swagger linter

LatestVersionOfCommonTypesMustBeUsed is the original ARM Swagger/Spectral rule being migrated.

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

The original Swagger linter performs these checks:

• Runs on every unresolved Swagger $ref value in ARM OpenAPI 2.0 specs (given: "$..['$ref']", resolved: false).
• Skips null references and references that do not match /common-types/resource-management/v\d+/\w+.json#.
• Extracts the referenced common-types version and filename from the matching $ref path.
• Looks up the expected latest version for that filename in LATEST_VERSION_BY_COMMON_TYPES_FILENAME.
• Reports a warning at the original $ref path when the referenced version does not equal the mapped latest version.
• Uses the validator's file-specific latest-version map: types.json, managedidentity.json, and privatelinks.json map to v6; customermanagedkeys.json, managedidentitywithdelegation.json, networksecurityperimeter.json, and mobo.json map to v5.

How the original Swagger linter works

The Swagger linter is a string-level emitted-Swagger check. Spectral visits each unresolved $ref, the function filters to ARM common-types references under /common-types/resource-management/v*/, then it splits the reference into {version}/{fileName}.json. If the extracted version is not equal to the hard-coded latest version for that filename, the linter reports:

Use the latest version {latestVersion} of {fileName}.

It does not inspect TypeSpec source, service namespaces, version enum members, payload visibility, or the authoring symbol that produced the emitted reference. This also means validator map entries are part of the observed behavior. In the current published validator, managedidentitywithdelegation.json and networksecurityperimeter.json are still mapped to v5, even though valid v6 copies exist in common-types. This PR deliberately does not copy those stale-map false positives.

How the migrated TypeSpec linter works

The migrated TypeSpec rule keeps the existing effective @armCommonTypesVersion selection check on ARM service namespaces and version enum members. When an API version already selects the latest common-types version, it additionally analyzes the TypeSpec symbols that would emit common-types $refs for that projected API.

For each service/API version, the rule applies the emitter's versioning mutator and analyzes the projected service graph. It then:

1. Traverses common types reachable from HTTP parameters, request bodies, response bodies, nested models, inherited properties, unions, tuples, arrays, and records.
2. Uses resolveRequestVisibility for requests and Visibility.Read for responses.
3. Filters properties through the same createMetadataInfo().isPayloadProperty and schema-sharing behavior used by AutoRest.
4. Applies Visibility.Item only to array elements; record additionalProperties keep their original payload context.
5. Resolves each emitted reference with getArmCommonTypeOpenAPIRef.
6. Reports the exact legacy parameter or definition against the user-reachable operation or property.
7. Deduplicates by diagnostic target and reference identity, while keeping traversal state distinct across payload contexts.

The reference diagnostic distinguishes the correct latest-version selection from the specific legacy symbol:

This API version already selects the latest ARM common-types version 'v6', but the common-type parameter 'LocationParameter' resolves to 'types.json' version 'v5'. Replace the TypeSpec usage that produces this legacy reference with a common type supported in 'v6'.

Migration evidence

Full focused-test evidence, real-service project comparison, latest full-corpus counts, one-sided project explanations, compile failures, review findings, and remaining uncertainty are documented in migration.md.

[Copilot]

Pull request overview

Extends the migrated lint rule to detect legacy ARM common-type references even when v6 is selected.

Changes:

• Traverses HTTP operation payloads and parameters for outdated references.
• Adds two regression fixtures and corpus migration evidence.
• Adds a reusable LintDiff rule-development skill.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
.github/skills/develop-lintdiff-rule/SKILL.md	Documents the rule workflow.
packages/typespec-lintdiff/src/rules/latest-version-of-common-types-must-be-used.ts	Implements reference-level validation.
packages/typespec-lintdiff/test/fixtures/LatestVersionOfCommonTypesMustBeUsed/rule.md	Documents updated behavior and fixtures.
packages/typespec-lintdiff/test/fixtures/LatestVersionOfCommonTypesMustBeUsed/migration.md	Records corpus parity evidence.
packages/typespec-lintdiff/test/fixtures/LatestVersionOfCommonTypesMustBeUsed/legacy-managed-identity/main.tsp	Defines the managed-identity regression.
packages/typespec-lintdiff/test/fixtures/LatestVersionOfCommonTypesMustBeUsed/legacy-managed-identity/expect.json	Marks the fixture as violating.
packages/typespec-lintdiff/test/fixtures/LatestVersionOfCommonTypesMustBeUsed/legacy-managed-identity/output.json	Snapshots emitted Swagger.
packages/typespec-lintdiff/test/fixtures/LatestVersionOfCommonTypesMustBeUsed/legacy-managed-identity/tsp-diagnostics.json	Snapshots TypeSpec diagnostics.
packages/typespec-lintdiff/test/fixtures/LatestVersionOfCommonTypesMustBeUsed/legacy-managed-identity/validator-diagnostics.json	Snapshots validator diagnostics.
packages/typespec-lintdiff/test/fixtures/LatestVersionOfCommonTypesMustBeUsed/legacy-location-parameter/main.tsp	Defines the location-parameter regression.
packages/typespec-lintdiff/test/fixtures/LatestVersionOfCommonTypesMustBeUsed/legacy-location-parameter/expect.json	Marks the fixture as violating.
packages/typespec-lintdiff/test/fixtures/LatestVersionOfCommonTypesMustBeUsed/legacy-location-parameter/output.json	Snapshots emitted Swagger.
packages/typespec-lintdiff/test/fixtures/LatestVersionOfCommonTypesMustBeUsed/legacy-location-parameter/tsp-diagnostics.json	Snapshots TypeSpec diagnostics.
packages/typespec-lintdiff/test/fixtures/LatestVersionOfCommonTypesMustBeUsed/legacy-location-parameter/validator-diagnostics.json	Snapshots validator diagnostics.

Suppressed comments (1)

packages/typespec-lintdiff/src/rules/latest-version-of-common-types-must-be-used.ts:92

• The unversioned path has the same undefined-selection problem: when no @armCommonTypesVersion is present, reportIfOutdated returns false and this scan resolves the default v3 references while claiming the service already selected latest v6. Gate reference diagnostics on currentVersion === latestVersion, and decide separately whether an omitted selection needs a selection-level warning.

            reportOutdatedUsages(

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[catalinaperalta]

Thanks for the detailed PR description, it's really helpful! I'm reviewing the PR, but I was thinking we should include some additional data in the PRs to review so that we can have increased certainty that the rule is providing the coverage we need. For each of the typespec lint PRs that are migrating a lintdiff rule, could we include the following:

• Include a link in the PR description to the lintdiff rule description and have copilot list out all the specific checks the original rule performs.
• Run the cross repo comparison script and add a comment on the PR with the table of the specs that reported the lintdiff rule and an output of whether the typespec lint was also reported for that spec? (I think copilot can add a small modification to the script so that the report creates a table focused on 1 rule)
• We could also attempt to add a couple of tests that mimic real world scenarios from a couple of select specs in the azure-rest-api-spec repo to ensure we're getting reports on real world cases. The scenarios should be from existing specs that are violating a lintdiff rule and have a typespec implementation that should raise the same typespec lint.

Let me know what you think! We can discuss in the sync later

[catalinaperalta]

Four raw validator-only projects reference valid v6 copies of
networksecurityperimeter.json or
managedidentitywithdelegation.json. The published validator ruleset has a
stale hard-coded map that still labels v5 as latest, so reproducing those
findings would incorrectly recommend a downgrade.

A couple of questions about this comment, does it meant that these swaggers dont have a tsp equivalent? Likewise, how are we getting around the v5 reference as latest even though the swaggers have newer versions? Maybe we should also warn in this case that the author should update to the lastest version? If the original lintdiff rule didnt do this, then we should open tracking issues to improve the rules in cases like this.

[Yuchao Yan (msyyc)]

Thanks for the detailed PR description, it's really helpful! I'm reviewing the PR, but I was thinking we should include some additional data in the PRs to review so that we can have increased certainty that the rule is providing the coverage we need. For each of the typespec lint PRs that are migrating a lintdiff rule, could we include the following:

• Include a link in the PR description to the lintdiff rule description and have copilot list out all the specific checks the original rule performs.
• Run the cross repo comparison script and add a comment on the PR with the table of the specs that reported the lintdiff rule and an output of whether the typespec lint was also reported for that spec? (I think copilot can add a small modification to the script so that the report creates a table focused on 1 rule)
• We could also attempt to add a couple of tests that mimic real world scenarios from a couple of select specs in the azure-rest-api-spec repo to ensure we're getting reports on real world cases. The scenarios should be from existing specs that are violating a lintdiff rule and have a typespec implementation that should raise the same typespec lint.

Let me know what you think! We can discuss in the sync later

Discussed in today's meeting:

1. make sense and I will add the swagger linter link into PR description and migration.md so that reviewer could get the context directly
2. I do it in local machine and all the detailed result is in migration.md
3. currently we keep unit test and the unit test should cover the corner case and classic case

[catalinaperalta]

Thanks for the detailed PR description, it's really helpful! I'm reviewing the PR, but I was thinking we should include some additional data in the PRs to review so that we can have increased certainty that the rule is providing the coverage we need. For each of the typespec lint PRs that are migrating a lintdiff rule, could we include the following:

• Include a link in the PR description to the lintdiff rule description and have copilot list out all the specific checks the original rule performs.
• Run the cross repo comparison script and add a comment on the PR with the table of the specs that reported the lintdiff rule and an output of whether the typespec lint was also reported for that spec? (I think copilot can add a small modification to the script so that the report creates a table focused on 1 rule)
• We could also attempt to add a couple of tests that mimic real world scenarios from a couple of select specs in the azure-rest-api-spec repo to ensure we're getting reports on real world cases. The scenarios should be from existing specs that are violating a lintdiff rule and have a typespec implementation that should raise the same typespec lint.

Let me know what you think! We can discuss in the sync later

Discussed in today's meeting:

1. make sense and I will add the swagger linter link into PR description and migration.md so that reviewer could get the context directly
2. I do it in local machine and all the detailed result is in migration.md
3. currently we keep unit test and the unit test should cover the corner case and classic case

Yes just one thing to add to 1 is to include a checklist of the specific checks the original lintdiff rule performed to make sure we're covering all our bases in the migrated tsp rule.

[Yuchao Yan (msyyc)]

catalinaperalta

1. "Do these swaggers not have a tsp equivalent?"
   These are not missing TypeSpec equivalents or missed TypeSpec diagnostics. "Swagger-only" often means the Swagger corpus saw something the TypeSpec corpus did not. Here, the real cause is different: TypeSpec did compile/analyze the projects, but did not warn because the references are already v6.

2. "How are we getting around v5 being latest?"
   The Swagger validator uses a per-file hard-coded latest-version map. For networksecurityperimeter.json and managedidentitywithdelegation.json, that map still says v5. The TypeSpec rule instead uses the current ARM common-types version data and treats v6 as latest.

3. "Should we warn authors to update?"
   For those four validator-only projects, no: they already reference v6. Warning would tell users to "fix" valid v6 usage, effectively copying a validator data bug.

4. "Should we open tracking issues?"
   That's reasonable for the Swagger validator/ruleset stale map, but it is not a parity bug in this migrated TypeSpec rule. The migration note classifies it as validator-data false positives, not TypeSpec semantic misses.

[Yuchao Yan (msyyc)]

related with #5271