Skip to content

use-standard-operations

Id
@azure-tools/typespec-azure-core/use-standard-operations

Operations should be defined using a signature from the Azure.Core namespace.

Azure Data Plane services should use standard operations defined in the Azure Core library.

Impact

Section titled “Impact”
  • Area: API, SDK

Custom operations that bypass the standard templates can lose the resource semantics used by emitters and tooling.

❌ Incorrect

Section titled “❌ Incorrect”
op myResourceRead(): MyResource;
op myResourceCreate(@body resource: MyResource);

Using operations from Azure.Core.Foundations is not acceptable either.

op myResourceRead is Azure.Core.Foundations.Operation<{}, MyResource>;
op myResourceCreate is Azure.Core.Foundations.Operation<MyResource, void>;

✅ Correct

Section titled “✅ Correct”
alias ServiceTraits = SupportsRepeatableRequests &
  SupportsConditionalRequests &
  SupportsClientRequestId;


alias Operations = Azure.Core.ResourceOperations<ServiceTraits>;


op myResourceRead is Operations.ResourceRead<MyResource>;
op myResourceCreate is Operations.ResourceCreate<MyResource>;

Suppression

Section titled “Suppression”

Suppress only when required to match an existing API; otherwise use the standard operation templates.