Azure / Azure/typespec-azure

Linter: PATCH body parameter / model must be named `[Model]Patch`

Open
#4,447 2 comments 0 reactions 0 assignees View on GitHub
feature lib:tcgc linter
Dominant language
TypeScript
Stars
27
Forks
90
Avg merge
1d 22h
Merged PRs (30d)
156

Description

Parent: #4442

## Convention

**DO** The name of PATCH operation's body parameter should be `[Model]Patch`. For nested model props, use `Content` instead of `Patch`. The name of PUT/POST body should be `[Model]Content` or `[Model]Data`.

> Source: [Azure SDK for .NET Mgmt Naming Conventions](https://github.com/Azure/azure-sdk-for-net/blob/main/doc/dev/Mgmt-Naming-Conventions.md)

## Observed today

A scan of `Azure/azure-rest-api-specs` (334 `client.tsp` files, 10,754 csharp-scoped `@@clientName` decorators) shows **172** decorators currently encoding this rule by hand. Examples:

- `CheckNameAvailabilityParameters` → `AppConfigurationNameAvailabilityContent` (appconfiguration/resource-manager/Microsoft.AppConfiguration/AppConfiguration/client.tsp)
- `RegenerateKeyParameters` → `AppConfigurationRegenerateKeyContent` (appconfiguration/resource-manager/Microsoft.AppConfiguration/AppConfiguration/client.tsp)
- `ExtensionUpgradeParameters` → `ArcExtensionUpgradeContent` (azurestackhci/resource-manager/Microsoft.AzureStackHCI/StackHCI/client.tsp)
- `ExtensionPatchParameters` → `ArcExtensionPatchContent` (azurestackhci/resource-manager/Microsoft.AzureStackHCI/StackHCI/client.tsp)
- `VirtualMachineInstanceManagedDiskParameters` → `VirtualMachineInstanceManagedDiskContent` (azurestackhci/resource-manager/Microsoft.AzureStackHCI/StackHCIVM/client.tsp)
- `ActivateApplicationPackageParameters` → `BatchApplicationPackageActivateContent` (batch/resource-manager/Microsoft.Batch/Batch/client.tsp)

## Proposed linter

**Detection**

For each operation, look at HTTP verb and the type used as `@body`. Flag when:
- PATCH body type name doesn't end with `Patch` (and doesn't derive from `*ResourceData`).
- PUT/POST body type name doesn't end with `Content` or `Data`.
- Body model name ends with `Parameter`, `Parameters`, or `Request`.

**Auto-fix**

Suggest rename via `@@clientName`. Replace `Parameter(s)`/`Request` suffix with `Content` (or `Patch` for PATCH body).

**Scope**

The rule should be csharp-scoped — it only flags violations of the .NET convention, not the underlying TypeSpec name. It should suggest inserting a `@@clientName(..., "csharp")` override when the underlying TypeSpec name is intentional, or renaming the TypeSpec model when the convention applies cross-language.

## Acceptance criteria

- [ ] New lint rule registered in the appropriate ruleset (`@azure-tools/typespec-client-generator-core` or `@azure-tools/typespec-azure-resource-manager`).
- [ ] Doc page under `website/src/content/docs/docs/libraries/.../rules/`.
- [ ] Unit tests covering positive / negative cases and the auto-fix.
- [ ] A `.chronus/changes/` entry.

Contributor guide

Open the contributing guide

Research direction

Start by inspecting existing rules and registration in @azure-tools/typespec-client-generator-core and @azure-tools/typespec-azure-resource-manager. Review the documentation structure under website/src/content/docs/docs/libraries/.../rules/ and existing .chronus/changes/ entries, then add unit tests for positive, negative, and auto-fix cases. Done means the csharp-scoped rule, documentation, tests, and change entry are present.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation, testing, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.