[Swagger Linter Migration] ParametersSchemaAsTypeObject

.chronus/changes/promote-parameters-schema-as-type-object-2026-08-31.md

@@ -0,0 +1,8 @@
+---
+changeKind: feature
+packages:
+  - "@azure-tools/typespec-azure-resource-manager"
+  - "@azure-tools/typespec-azure-rulesets"
+---
+
+Add the `request-body-must-be-object` 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

@@ -66,6 +66,7 @@ Available ruleSets:
 | [`@azure-tools/typespec-azure-resource-manager/missing-operations-endpoint`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/missing-operations-endpoint)                             | Check for missing Operations interface.                                                                                                                                                                                                               |
 | [`@azure-tools/typespec-azure-resource-manager/patch-envelope`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/patch-envelope)                                                       | Patch envelope properties should match the resource properties.                                                                                                                                                                                       |
 | [`@azure-tools/typespec-azure-resource-manager/arm-resource-patch`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-resource-patch)                                               | Validate ARM PATCH operations.                                                                                                                                                                                                                        |
+| [`@azure-tools/typespec-azure-resource-manager/request-body-must-be-object`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/request-body-must-be-object)                             | Request bodies must resolve to object schemas.                                                                                                                                                                                                        |
 | [`@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.                                                                                                                                                                                                                      |

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

@@ -34,6 +34,7 @@ import { deleteOperationMissingRule } from "./rules/no-resource-delete-operation
 import { noResponseBodyRule } from "./rules/no-response-body.js";
 import { operationsInterfaceMissingRule } from "./rules/operations-interface-missing.js";
 import { patchEnvelopePropertiesRules } from "./rules/patch-envelope-properties.js";
+import { requestBodyMustBeObjectRule } from "./rules/request-body-must-be-object.js";
 import { resourceNameRule } from "./rules/resource-name.js";
 import { retryAfterRule } from "./rules/retry-after.js";
 import { secretProprule } from "./rules/secret-prop.js";
@@ -83,6 +84,7 @@ const rules = [
   operationsInterfaceMissingRule,
   patchEnvelopePropertiesRules,
   patchOperationsRule,
+  requestBodyMustBeObjectRule,
   resourceNameRule,
   retryAfterRule,
   unsupportedTypeRule,

packages/typespec-azure-resource-manager/src/rules/request-body-must-be-object.md

@@ -0,0 +1,58 @@
+Use an object model for every Azure Resource Manager request body that has an explicit schema type.
+
+## Impact
+
+- **Area:** API, SDK
+
+Object 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 an object 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).