[Swagger Linter Migration] ParametersInPost

[Yuchao Yan (msyyc)]

Original Swagger linter

• linter code: ParametersInPost
• linter doc: parameters-in-post.md

The original rule checks:

• Applies to ARM OpenAPI specs (RPC-POST-V1-05).
• For each POST operation parameter, find parameters where in === "query".
• Exempt only the exact query parameter name api-version.
• Report every remaining query parameter on the POST operation.
• Message that POST operation query parameters must be moved into the payload.

How the Swagger linter works

The Spectral function receives the Swagger POST operation parameters array. It returns no diagnostics when the value is not an array or is empty. Otherwise it filters the operation parameters with param.in === "query" && param.name !== "api-version", then emits one diagnostic per matching parameter. The diagnostic path is the Spectral context path for the operation parameters rather than the individual TypeSpec source parameter.

The Swagger rule reports emitted OpenAPI occurrences, so its raw diagnostic cardinality can differ from a semantic TypeSpec rule. The migration evidence notes one known cardinality skew in HybridConnectivity where Swagger emits two POST parameter occurrences while TypeSpec reports four semantic source locations for expiresin; that is not a project coverage gap.

Source TypeSpec lintdiff rule

• Validator rule id: ParametersInPost
• Local lintdiff rule name: parameters-in-post
• Canonical validator rule slug: parameters-in-post
• Source branch: feature/lintdiff-parameters-in-post
• Source commit: e56688697d812f0c46ac0a5c15dc00aa038d708e
• Source worktree: C:\dev\worktrees\typespec-azure-lintdiff-parameters-in-post
• Source worktree uncommitted rule changes: none observed for the inspected source/evidence files
• Source rule file: https://github.com/msyyc/typespec-azure/blob/feature/lintdiff-parameters-in-post/packages/typespec-lintdiff/src/rules/parameters-in-post.ts

The user-marked done source rule was not modified during promotion.

Destination analysis

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

Evidence:

• The fixture front matter says ParametersInPost applies to Resource Manager (ARM).
• Validator metadata has applicability: ARM, sources: ["arm"], severity error, and RPC code RPC-POST-V1-05.
• The lintdiff implementation depends on ARM semantics via isArmProviderNamespace.
• The rule checks ARM POST operations, including non-resource ARM POST operations, and does not apply to data-plane services.
• docs/validate-report.md inferred the fixture rows as resource-manager.
• No existing official ARM/core rule was found with equivalent coverage.

Plausible alternative: @azure-tools/typespec-azure-core, but that would either over-scope an ARM-only RPC rule to data-plane services or require a rewrite that removes the ARM provider namespace boundary. The ARM package keeps the dependency direction correct and matches the source semantics.

How the promoted TypeSpec linter works

The promoted rule is @azure-tools/typespec-azure-resource-manager/no-query-parameters-in-post. It registers in the ARM linter and the resource-manager ruleset.

For each operation, it:

1. Resolves the operation namespace from the containing interface namespace or operation namespace.
2. Uses isArmProviderNamespace to keep the rule scoped to ARM provider namespaces.
3. Uses getHttpOperation to inspect the HTTP verb and parameters.
4. Skips non-POST operations.
5. Reports each HTTP query parameter whose serialized name is not exactly api-version.
6. Targets the authorable TypeSpec parameter (parameter.param) and includes the query name in the diagnostic message.

Intentional promotion adaptation: the official rule uses an exact name === "api-version" exemption to match the original Swagger validator. During final review, the lintdiff source was found to use a case-insensitive helper; the source branch remains unchanged, and this PR documents the sync note below.

Fixture-to-native test mapping

• query-param-in-post -> emits one warning for mode on an ARM POST resource action.
• multiple-query-params -> emits one warning each for mode and format on the same ARM POST operation.
• non-resource-post-query -> emits a warning for $filter on a non-resource ARM POST operation.
• api-version-only -> remains valid when the only query parameter is the standard api-version supplied by ARM templates.
• Review regression: @query("API-Version") emits a warning, matching the Swagger validator's exact-name api-version exemption.
• Additional compliant case: non-ARM POST operations are ignored even when they have query parameters.

Migration evidence

Migration evidence is captured in the source branch's migration.md, including the focused tests, real-service project comparison, latest full-corpus counts, one-sided project explanations, compile failures, diagnostic cardinality notes, and final uncertainty statement.

Validation

Targeted validation completed:

• pnpm -r --filter "@azure-tools/typespec-azure-resource-manager..." build
• pnpm --filter @azure-tools/typespec-azure-resource-manager exec vitest run test/rules/no-query-parameters-in-post.test.ts (6 tests)
• 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 run format:check
• pnpm --filter "@azure-tools/typespec-azure-website..." run build
• pnpm --filter @azure-tools/typespec-azure-rulesets build
• pnpm --filter @azure-tools/typespec-azure-rulesets test
• pnpm --filter @azure-tools/typespec-azure-resource-manager test (passed after rerun; the first full-package run timed out once in existing test/enforce-constraint.test.ts, and that test file passed when rerun directly)
• git diff --check

Validation blocker

pnpm validate:pr was run with a bounded wait. It completed step 1, Branch is up to date, in 3.7s, then produced no further progress during the 5-minute bound. Because the targeted package, docs, website, rulesets, formatting, and diff validations above passed, the stalled broad pre-PR run was stopped and treated as an environmental/pre-existing validation blocker.

Promotion sync policy

The lintdiff source branch remains the source of truth for the migration PR and was not changed during this promotion. If reviewers decide the source lintdiff rule must also use exact api-version matching, that should be handled by explicitly reopening lintdiff repair for ParametersInPost; this promotion PR should stay synchronized with the approved source or be blocked until that repair is completed.

This new ARM rule could affect existing Azure service specs, so the int:azure-specs label is appropriate.

[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-rulesets - feature ✏️

Enable the ARM no-query-in-post lint rule in the resource manager ruleset.

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

Add the no-query-in-post ARM lint rule to warn when POST operations declare query parameters other than api-version.

[github-actions]

📦 Package size report

2 packages changed size, +6.23 KB (+0.0%) packed overall.

Package	Packed (base → head)	Δ Packed	Unpacked (base → head)	Δ Unpacked
@azure-tools/typespec-ts	532.67 KB → 536.71 KB	+4.04 KB (+0.8%) 🔴	2.56 MB → 2.58 MB	+17.91 KB (+0.7%) 🔴
@azure-tools/typespec-go	258.44 KB → 260.21 KB	+1.77 KB (+0.7%) 🔴	1.32 MB → 1.33 MB	+9.47 KB (+0.7%) 🔴

11 package(s) with no notable change

Package	Packed (base → head)	Δ Packed	Unpacked (base → head)	Δ Unpacked
@azure-tools/typespec-client-generator-core	229.25 KB → 229.48 KB	+229 B (+0.1%)	1.23 MB → 1.23 MB	+937 B (+0.1%)
@azure-tools/azure-http-specs	146.63 KB → 146.71 KB	+80 B (+0.1%)	1.16 MB → 1.16 MB	+415 B (+0.0%)
@azure-tools/typespec-azure-resource-manager	172.59 KB → 172.65 KB	+63 B (+0.0%)	1.05 MB → 1.05 MB	+615 B (+0.1%)
@azure-tools/typespec-java	13.51 MB → 13.51 MB	+37 B (+0.0%)	15.03 MB → 15.03 MB	—
@azure-tools/typespec-azure-rulesets	5.16 KB → 5.18 KB	+20 B (+0.4%)	32.09 KB → 32.27 KB	+184 B (+0.6%)
@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	—
@azure-tools/typespec-python	42.22 KB → 42.22 KB	—	164.91 KB → 164.91 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@5281

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

commit: 22f4b79

[azure-sdk-automation]

You can try these changes here

🛝 Playground	🌐 Website

[catalinaperalta]

overall lgtm, left a question about the api version casing but we could improve it later on

[Timothee Guerin (timotheeguerin)]

this is defined in use-api-version.ts rule can we share the helper(move it to common place)

[Yuchao Yan (msyyc)]

I kept these helpers separate because they answer different questions. This rule checks the exact serialized HTTP query name (api-version) for Swagger parity, while use-api-version.ts checks whether a model property originates from the common-types ApiVersionParameter. Sharing that helper would change this rule's semantics.

[Timothee Guerin (timotheeguerin)]

still should at least share it across the new rules you add

[Mark Cowlishaw (markcowl)]

Looks good, a few comments

[Yuchao Yan (msyyc)]

Timothee Guerin (@timotheeguerin) / Mark Cowlishaw (@markcowl) Thanks for your review. I updated PR with your suggestions and pls help take a review again.