Azure / Azure/azure-rest-api-specs
ARM API Reviewer agent: inspect x-ms-skip-url-encoding usage on path parameters
- Dominant language
- TypeSpec
- Stars
- 3.1k
- Forks
- 5.9k
- Avg merge
- 3d 2h
- Merged PRs (30d)
- 424
Description
### 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](https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/creating-swagger.md#control-url-encoding-with-x-ms-skip-url-encoding)
- AutoRest extension docs — [x-ms-skip-url-encoding](https://github.com/Azure/autorest/blob/main/docs/extensions/readme.md#x-ms-skip-url-encoding)
- Related Spectral / OpenAPI authoring rules — [openapi-authoring-automated-guidelines.md](https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/openapi-authoring-automated-guidelines.md)
- Agent instruction files to update:
- [.github/instructions/openapi-review.instructions.md](https://github.com/Azure/azure-rest-api-specs/blob/main/.github/instructions/openapi-review.instructions.md)
- [.github/instructions/armapi-review.instructions.md](https://github.com/Azure/azure-rest-api-specs/blob/main/.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.
Contributor guide
Assessment
This issue has not been assessed yet.