ARM API Reviewer agent: inspect x-ms-skip-url-encoding usage on path parameters

[ravimeda]

Background

x-ms-skip-url-encoding: true disables AutoRest''s automatic URL-encoding of a path or query parameter value. It is appropriate only when the value is known to already be URL-encoded or legitimately contains reserved characters (e.g., multi-segment paths, fully-qualified ARM resource IDs / {scope}, SAS tokens, URLs). Misuse leads to:

• Broken request URLs when values contain /, %, #, ?, etc.
• Potential path/query injection when values are user-controlled.
• Breaking SDK changes when the flag is added or removed between API versions.

The ARM API Reviewer agent does not currently have a dedicated rule for this extension. It is only inspected ad hoc as part of general parameter review.

References

• Repo docs — Control URL encoding with x-ms-skip-url-encoding
• AutoRest extension docs — x-ms-skip-url-encoding
• Related Spectral / OpenAPI authoring rules — openapi-authoring-automated-guidelines.md
• Agent instruction files to update:
  • .github/instructions/openapi-review.instructions.md
  • .github/instructions/armapi-review.instructions.md

Requested work

1. Add a rule (e.g., ARM-PATH-ENCODING-V1) to the OpenAPI and ARM review instruction files listed above, and include it in their "Review Checklist Summary" sections.
2. Rule semantics:
   • Flag any path parameter with x-ms-skip-url-encoding: true whose value is a single ARM path segment (e.g., a tracked/proxy resource {resourceName}). These must be URL-encoded normally.
   • Allow the extension on parameters that legitimately carry multi-segment paths ({scope}, nested resource IDs, blob paths), but require the parameter description to justify why encoding must be skipped.
   • Flag query parameters using the extension without a clear, specific reason in the description.
   • Cross-version check: adding or removing the extension on an existing parameter between API versions is a potential SDK breaking change and must be reported under the breaking-change comparison step.
3. Test fixtures under .github/shared/test/fixtures/ covering:
   • Legitimate use on a {scope} parameter (should pass).
   • Illegitimate use on a resource name parameter (should flag as blocking).
   • Version-to-version flip of the extension (should flag as breaking).
4. (Optional follow-up) Investigate whether an existing Spectral rule covers this and, if not, file a follow-up to add deterministic CI enforcement rather than agent-only.

Acceptance criteria

• Agent reports x-ms-skip-url-encoding findings under a stable rule ID with [NEW] / [EXISTING] classification.
• Each finding''s "Fix" guidance links to both reference docs above so the spec author can understand the extension''s intent and correct usage.
• Reviewing a PR that introduces x-ms-skip-url-encoding: true on a resource-name path parameter produces a blocking finding; reviewing legitimate use on a {scope} parameter does not.