[Swagger Linter Migration] ParametersSchemaAsTypeObject

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

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@azure-tools/typespec-azure-resource-manager"
+---
+
+Add the `use-model-request-body` ARM lint rule, an idiomatic TypeSpec migration of the Swagger `ParametersSchemaAsTypeObject` validator rule.

.chronus/changes/register-use-model-request-body-ruleset.md

@@ -0,0 +1,7 @@
+---
+changeKind: internal
+packages:
+  - "@azure-tools/typespec-azure-rulesets"
+---
+
+Register the ARM `use-model-request-body` lint rule as disabled in the resource manager ruleset.

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

@@ -75,6 +75,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 plain 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

@@ -48,6 +48,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";
@@ -100,6 +101,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,52 @@
+Use a plain model for every Azure Resource Manager request body.
+
+## Impact
+
+- **Area:** API, SDK
+
+Plain model request bodies can evolve by adding optional properties without changing the top-level wire shape. Primitive, union, array, and record bodies cannot gain new fields without a breaking API and generated-SDK change.
+
+A plain model is a TypeSpec model without an indexer. This rule evaluates the authored TypeSpec shape rather than reproducing emitter-specific Swagger schema behavior. Operations without a request body and multipart request bodies are allowed.
+
+## Incorrect
+
+```tsp
+@post
+op submit(@body body: string): void;
+
+model ItemList is Array<string>;
+
+@post
+op submitItems(@body body: ItemList): void;
+
+model Metadata is Record<string>;
+
+@post
+op submitMetadata(@body body: Metadata): 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;
+```
+
+## Suppression
+
+Suppress only when required to preserve an existing API; otherwise replace the request body with a model without an indexer.
+
+## LintDiff Origin
+
+This rule is the idiomatic TypeSpec equivalent of the Swagger validator rule [ParametersSchemaAsTypeObject](https://github.com/Azure/azure-openapi-validator/blob/main/docs/parameters-schema-as-type-object.md). It intentionally validates TypeSpec model semantics instead of simulating AutoRest's emitted Swagger schema details.

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

@@ -0,0 +1,48 @@
+import { createRule, fileRef, getLocationContext, isVoidType, type Type } from "@typespec/compiler";
+import { getHttpOperation } from "@typespec/http";
+
+export const useModelRequestBodyRule = createRule({
+  name: "use-model-request-body",
+  docs: fileRef.fromPackageRoot("src/rules/use-model-request-body.md"),
+  description: "Request bodies must use plain models.",
+  severity: "warning",
+  url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/use-model-request-body",
+  messages: {
+    default:
+      "Request bodies must use plain models. Replace this body type with a model without an indexer.",
+  },
+  create(context) {
+    return {
+      operation: (operation) => {
+        const [httpOperation] = getHttpOperation(context.program, operation);
+        const body = httpOperation.parameters.body;
+        if (body === undefined || body.bodyKind === "multipart") {
+          return;
+        }
+
+        const bodyType = getUnderlyingType(body.type);
+        if (isVoidType(bodyType) || (body.bodyKind === "single" && isPlainModel(bodyType))) {
+          return;
+        }
+
+        context.reportDiagnostic({
+          target:
+            body.property && getLocationContext(context.program, body.property).type === "project"
+              ? body.property
+              : operation,
+        });
+      },
+    };
+  },
+});
+
+function getUnderlyingType(type: Type): Type {
+  while (type.kind === "ModelProperty") {
+    type = type.type;
+  }
+  return type;
+}
+
+function isPlainModel(type: Type): boolean {
+  return type.kind === "Model" && type.indexer === undefined;
+}