TypeSpec Authoring Docs: cover adding standard $top/$skip query parameters to ARM list operations

[haolingdong-msft]

Documentation gap: adding standard $top/$skip query parameters to an ARM list operation

Summary

The Azure TypeSpec (ARM / Azure.ResourceManager) documentation does not clearly show how to add standard pagination query parameters ($top, $skip) to an ArmListBySubscription (or other Arm list) operation using the canonical, reusable parameter models.

The reusable building blocks exist — TopQueryParameter, SkipQueryParameter, Azure.Core.StandardListQueryParameters, and ArmTopParameter & ArmSkipParameter — but there is no documented example showing how to pass them as the Parameters argument of an Arm list template. As a result, an agent (and a human) tends to hand-roll a custom model with raw @query("$top") / @query("$skip") properties instead of reusing the standard types, producing inconsistent, non-idiomatic API surface.

Case / scenario

Add $top and $skip query parameters to an existing listBySubscription operation on an ARM resource interface.

Prompt

add top and skip query parameters to the ListBySubscription operation in interface Employees

Input code

employee.tsp:

@armResourceOperations
interface Employees {
  get is ArmResourceRead<Employee>;
  createOrUpdate is ArmResourceCreateOrReplaceAsync<Employee>;
  update is ArmResourcePatchSync<Employee, EmployeeProperties>;
  delete is ArmResourceDeleteWithoutOkAsync<Employee>;
  listByResourceGroup is ArmResourceListByParent<Employee>;
  listBySubscription is ArmListBySubscription<Employee>;
}

Expected code

Any of the following idiomatic forms (reusing the standard parameter types) should be documented:

// Option A — spread the standard ARM query parameter models
listBySubscription is ArmListBySubscription<
  Employee,
  {
    ...TopQueryParameter;
    ...SkipQueryParameter;
  }
>;

// Option B — intersect the standard ARM parameter models
listBySubscription is ArmListBySubscription<
  Employee,
  Parameters = ArmTopParameter & ArmSkipParameter
>;

// Option C — reuse Azure.Core.StandardListQueryParameters
model EmployeeListBySubscriptionParameters
  is Azure.Core.StandardListQueryParameters;

listBySubscription is ArmListBySubscription<
  Employee,
  EmployeeListBySubscriptionParameters
>;

This is preferable to hand-rolling raw query params, which is what authors fall back to today when the pattern is undocumented:

// Anti-pattern (avoid) — reinvents standard parameters
model ListBySubscriptionQueryParameters {
  @query("$top") top?: int32;
  @query("$skip") skip?: int32;
}
listBySubscription is ArmListBySubscription<Employee, ListBySubscriptionQueryParameters>;

Request

Please add documentation (with a worked example like the above) showing how to add optional/standard query parameters such as $top and $skip to ARM list operations using the canonical TopQueryParameter/SkipQueryParameter, ArmTopParameter & ArmSkipParameter, or Azure.Core.StandardListQueryParameters types — and clarify which form is recommended.