[Swagger Linter Migration] ParametersSchemaAsTypeObject

.chronus/changes/promote-use-model-request-body-2026-08-31.md

@@ -0,0 +1,8 @@
+---
+changeKind: feature
+packages:
+  - "@azure-tools/typespec-azure-resource-manager"
+  - "@azure-tools/typespec-azure-rulesets"
+---
+
+Add the `use-model-request-body` ARM lint rule, migrated from the Swagger `ParametersSchemaAsTypeObject` validator rule and disabled by default in the resource-manager ruleset.

packages/typespec-azure-resource-manager/README.md

@@ -71,6 +71,7 @@ Available ruleSets:
 | [`@azure-tools/typespec-azure-resource-manager/resource-name`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/resource-name)                                                         | Check the resource name.                                                                                                                                                                                                                              |
 | [`@azure-tools/typespec-azure-resource-manager/retry-after`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/retry-after)                                                             | Check if retry-after header appears in response body.                                                                                                                                                                                                 |
 | [`@azure-tools/typespec-azure-resource-manager/unsupported-type`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/unsupported-type)                                                   | Check for unsupported ARM types.                                                                                                                                                                                                                      |
+| [`@azure-tools/typespec-azure-resource-manager/use-model-request-body`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/use-model-request-body)                                       | Request bodies must use models.                                                                                                                                                                                                                       |
 | [`@azure-tools/typespec-azure-resource-manager/secret-prop`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/secret-prop)                                                             | RPC-v1-13: Check that property with names indicating sensitive information(e.g. contains auth, password, token, secret, etc.) are marked with @secret decorator.                                                                                      |
 | [`@azure-tools/typespec-azure-resource-manager/no-empty-model`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/no-empty-model)                                                       | ARM Properties with type:object that don't reference a model definition are not allowed. ARM doesn't allow generic type definitions as this leads to bad customer experience.                                                                         |
 | [`@azure-tools/typespec-azure-resource-manager/no-reserved-resource-property`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/no-reserved-resource-property)                         | Reserved property names (for example 'billingData') must not be present in a resource's property bag. The property name is matched case-insensitively.                                                                                                |

packages/typespec-azure-resource-manager/src/linter.ts

@@ -43,6 +43,7 @@ import { unsupportedTypeRule } from "./rules/unsupported-type.js";
 import { useApiVersionRule } from "./rules/use-api-version.js";
 import { useApplicationJsonContentTypeRule } from "./rules/use-application-json-content-type.js";
 import { useInterfaceRule } from "./rules/use-interface.js";
+import { useModelRequestBodyRule } from "./rules/use-model-request-body.js";
 import { useOperationDecoratorRule } from "./rules/use-operation-decorator.js";
 import { useRelationshipRequiredPropertiesRule } from "./rules/use-relationship-required-properties.js";
 import { versionProgressionRule } from "./rules/version-progression.js";
@@ -91,6 +92,7 @@ const rules = [
   resourceNameRule,
   retryAfterRule,
   unsupportedTypeRule,
+  useModelRequestBodyRule,
   secretProprule,
   noEmptyModel,
   noReservedResourcePropertyRule,

packages/typespec-azure-resource-manager/src/rules/use-model-request-body.md

@@ -0,0 +1,58 @@
+Use a model for every Azure Resource Manager request body that has an explicit schema type.
+
+## Impact
+
+- **Area:** API, SDK
+
+Model request bodies can evolve by adding optional properties without changing the top-level wire shape. Primitive and array bodies cannot gain new fields without a breaking API and generated-SDK change.
+
+Schemas without an explicit type, such as `unknown` and unsupported model unions, are outside this rule's scope. Nullable and singleton unions use their effective emitted schema type, while unions emitted as string or number enums are rejected. Operations without a request body are also allowed.
+
+## Incorrect
+
+```tsp
+@post
+op submit(@body body: string): void;
+
+model ItemList is Array<string>;
+
+@post
+op submitItems(@body body: ItemList): void;
+
+union ActionMode {
+  "fast",
+  "safe",
+}
+
+@post
+op runAction(@body body: ActionMode): void;
+```
+
+## Correct
+
+```tsp
+model SubmitRequest {
+  value: string;
+}
+
+@post
+op submit(@body body: SubmitRequest): void;
+
+model SubmitItemsRequest {
+  items: string[];
+}
+
+@post
+op submitItems(@body body: SubmitItemsRequest): void;
+
+@post
+op submitNullable(@body body: SubmitRequest | null): void;
+```
+
+## Suppression
+
+Suppress only when required to preserve an existing API; otherwise replace the request body with a model.
+
+## LintDiff Equivalent
+
+This rule corresponds to the Swagger validator rule [ParametersSchemaAsTypeObject](https://github.com/Azure/azure-openapi-validator/blob/main/docs/parameters-schema-as-type-object.md).