use-scope-for-extension-routing

Id

@azure-tools/typespec-azure-resource-manager/use-scope-for-extension-routing

Require scope-based paths when explicitly enabled for RPaaS extension routing.

For Resource Provider as a Service (RPaaS) extension-routing contracts, accept an arbitrary scope instead of embedding a specific parent resource URI. RPaaS does not forward that parent URI to the provider-side extension route.

This rule warns when an operation’s resolved HTTP path contains more than one literal, case-sensitive /providers/ segment. It reports once per concrete operation, including inherited endpoints, and skips uninstantiated templates. It checks the supplied program, not a selected API-version projection.

This is not a general ARM path restriction. Specific-parent extension paths are supported ordinary ARM endpoints. This guidance applies to contracts intended for RPaaS extension routing; it does not identify a service’s deployment audience. Managed RPaaS configurations select this rule explicitly. The general ARM all and Azure resource-manager rulesets do not enable this RPaaS-specific policy.

Impact

• Area: API, SDK

Embedding a parent URI in a provider-side extension route can make the route incompatible with RPaaS routing and produce unusable client operations. This routing impact applies to RPaaS contracts, not ordinary ARM endpoints.

❌ Incorrect

The extension read operation embeds a specific virtual machine’s parent URI.

alias VirtualMachine = Extension.ExternalResource<"Microsoft.Compute", "virtualMachines", "vmName">;

@armResourceOperations
interface Bindings {
  read is Extension.Read<VirtualMachine, Binding>;
}

✅ Correct

Accept an arbitrary scope with the same resource and read operation.

@armResourceOperations
interface Bindings {
  read is Extension.Read<Extension.ScopeParameter, Binding>;
}

Suppression

Prefer an arbitrary-scope extension template for RPaaS routing. For an intentional RPaaS routing exception approved by the service’s routing reviewers, suppress the fully qualified rule on the offending operation with a reason documenting that approval. Supported ordinary ARM endpoints are not RPaaS routing exceptions.

LintDiff Equivalent

This rule corresponds to R4038 ExtensionResourcePathPattern. The original validator implementation is documented in ExtensionResourcePathPattern. The native rule reports per authored concrete operation rather than per emitted path, so separate verbs on one path can produce separate warnings.