feat(typespec-autorest): add type-name-strategy option to remove namespace prefix from names (#4660)

Fixes #2055

## Problem

`@azure-tools/typespec-autorest` prepends the namespace to model names
when generating Swagger definition names (e.g.
`LiftrBase.MarketplaceDetails`). Client emitters (C#, PowerShell, etc.)
ignore the namespace and use just the type name (`MarketplaceDetails`).
This inconsistency causes breaking changes when migrating from
swagger-based codegen to TypeSpec-native codegen.

## Change

Adds a new emitter option `type-name-strategy`:

- `"namespaced"` (default): current behavior — names include the
namespace prefix for types outside the service namespace (e.g.
`LiftrBase.Foo`). The service (and root `TypeSpec`) namespace is always
stripped.
- `"name-only"`: names use only the type name without any namespace
prefix (e.g. `Foo`), matching what client emitters produce.

```yaml
options:
  "@azure-tools/typespec-autorest":
    type-name-strategy: "name-only"
```

The strategy applies globally to all OpenAPI names derived from TypeSpec
types (definition/schema names, parameter keys, inline names,
`x-typespec-name`) via the shared `namespaceFilter`, keeping everything
consistent.

When two types from different namespaces collapse to the same name, the
existing `@typespec/openapi/duplicate-type-name` error is reported (no
auto fallback to the qualified name). `@clientName` and `@friendlyName`
continue to take precedence.

## Backward compatibility

Default is `"namespaced"`, so existing behavior is unchanged unless the
option is explicitly set to `"name-only"`.

## Tests

Added `packages/typespec-autorest/test/type-name-strategy.test.ts`
covering:
- default / explicit `namespaced` keeps the prefix, and same-named types
in different namespaces coexist
- `name-only` removes the prefix from definitions
- `name-only` collision across namespaces errors with
`duplicate-type-name`
- `@friendlyName` still wins under `name-only`

Author: timotheeguerin

.chronus/changes/autorest-type-name-strategy-2026-6-18-12-15-0.md

@@ -0,0 +1,13 @@
+---
+changeKind: feature
+packages:
+  - "@azure-tools/typespec-autorest"
+---
+
+Add `type-name-strategy` emitter option to control how OpenAPI names are derived from TypeSpec types. The new `"name-only"` strategy removes the namespace prefix from names (e.g. `Foo` instead of `LiftrBase.Foo`), matching the names used by client emitters. The default `"namespaced"` keeps the current behavior. When two types collapse to the same name, a `duplicate-type-name` error is reported.
+
+```yaml
+options:
+  "@azure-tools/typespec-autorest":
+    type-name-strategy: "name-only"
+```

packages/typespec-autorest/README.md

@@ -196,6 +196,14 @@ Determines whether output should be split into multiple files. The only supporte
 
 When enabled, the emitter will not copy example files to the output directory. Instead, it will reference the source example files using relative file paths.
 
+### `type-name-strategy`
+
+**Type:** `"namespaced" | "name-only"`
+
+**Default:** `"namespaced"`
+
+Strategy for naming the OpenAPI names derived from TypeSpec types. "namespaced" (default) includes the namespace prefix for types outside the service namespace (e.g. `LiftrBase.Foo`). "name-only" uses only the type name without any namespace prefix (e.g. `Foo`), reporting an error when two types collapse to the same name.
+
 ## Decorators
 
 ### Autorest

packages/typespec-autorest/src/emit.ts

@@ -116,6 +116,7 @@ export function resolveAutorestOptions(
     xmlStrategy: resolvedOptions["xml-strategy"],
     outputSplitting: resolvedOptions["output-splitting"],
     skipExampleCopying: resolvedOptions["skip-example-copying"],
+    typeNameStrategy: resolvedOptions["type-name-strategy"],
   };
 }
 

packages/typespec-autorest/src/lib.ts

@@ -125,6 +125,21 @@ export interface AutorestEmitterOptions {
    * @default false
    */
   "skip-example-copying"?: boolean;
+
+  /**
+   * Strategy for naming the OpenAPI names derived from TypeSpec types (definition/schema
+   * names, parameter keys, inline names, `x-typespec-name`, etc.).
+   *
+   * - `"namespaced"`: Include the namespace prefix when a type lives outside the service namespace
+   *   (e.g. `LiftrBase.Foo`). The service (and root `TypeSpec`) namespace is always stripped. This
+   *   is the current/default behavior.
+   * - `"name-only"`: Use only the type name without any namespace prefix (e.g. `Foo`). When two
+   *   types from different namespaces collapse to the same name, the conflict is reported as an
+   *   error (`@typespec/openapi/duplicate-type-name`).
+   *
+   * @default "namespaced"
+   */
+  "type-name-strategy"?: "namespaced" | "name-only";
 }
 
 const EmitterOptionsSchema: JSONSchemaType<AutorestEmitterOptions> = {
@@ -268,6 +283,14 @@ const EmitterOptionsSchema: JSONSchemaType<AutorestEmitterOptions> = {
       description:
         "When enabled, the emitter will not copy example files to the output directory. Instead, it will reference the source example files using relative file paths.",
     },
+    "type-name-strategy": {
+      type: "string",
+      enum: ["namespaced", "name-only"],
+      nullable: true,
+      default: "namespaced",
+      description:
+        'Strategy for naming the OpenAPI names derived from TypeSpec types. "namespaced" (default) includes the namespace prefix for types outside the service namespace (e.g. `LiftrBase.Foo`). "name-only" uses only the type name without any namespace prefix (e.g. `Foo`), reporting an error when two types collapse to the same name.',
+    },
   },
   required: [],
 };

packages/typespec-autorest/src/openapi.ts

@@ -262,6 +262,18 @@ export interface AutorestDocumentEmitterOptions {
    * @default false
    */
   readonly skipExampleCopying?: boolean;
+
+  /**
+   * Strategy for naming the OpenAPI names derived from TypeSpec types (definition/schema
+   * names, parameter keys, inline names, `x-typespec-name`, etc.).
+   *
+   * - `"namespaced"`: Include the namespace prefix for types outside the service namespace
+   *   (e.g. `LiftrBase.Foo`). Default.
+   * - `"name-only"`: Use only the type name without any namespace prefix (e.g. `Foo`). Conflicts are
+   *   reported as an error.
+   * @default "namespaced"
+   */
+  readonly typeNameStrategy?: "namespaced" | "name-only";
 }
 
 type HttpParameterProperties = Extract<
@@ -279,6 +291,11 @@ export async function getOpenAPIForService(
   const typeNameOptions: TypeNameOptions = {
     // shorten type names by removing TypeSpec and service namespace
     namespaceFilter(ns) {
+      // With the "name-only" strategy, strip every namespace so names are not prefixed by their
+      // namespace (e.g. `Foo` instead of `LiftrBase.Foo`).
+      if (options.typeNameStrategy === "name-only") {
+        return false;
+      }
       return !isService(program, ns);
     },
   };

packages/typespec-autorest/test/type-name-strategy.test.ts

@@ -0,0 +1,82 @@
+import { expectDiagnostics } from "@typespec/compiler/testing";
+import { describe, expect, it } from "vitest";
+import { compileOpenAPI, diagnoseOpenApiFor } from "./test-host.js";
+
+const code = `
+  @service
+  namespace MyService;
+
+  namespace LiftrBase {
+    model MarketplaceDetails {}
+  }
+
+  op read(): LiftrBase.MarketplaceDetails;
+`;
+
+// Two models with the same name in different namespaces.
+const sameNameInDifferentNamespaces = `
+  @service
+  namespace MyService;
+
+  namespace LiftrBase {
+    model Widget {}
+  }
+  namespace Other {
+    model Widget {}
+  }
+
+  @route("/a") op a(): LiftrBase.Widget;
+  @route("/b") op b(): Other.Widget;
+`;
+
+describe("default (namespaced)", () => {
+  it("keeps the namespace prefix in the definition name", async () => {
+    const oapi = await compileOpenAPI(code);
+    expect(oapi.definitions).toHaveProperty(["LiftrBase.MarketplaceDetails"]);
+  });
+
+  it("is the behavior when type-name-strategy is explicitly namespaced", async () => {
+    const oapi = await compileOpenAPI(code, { options: { "type-name-strategy": "namespaced" } });
+    expect(oapi.definitions).toHaveProperty(["LiftrBase.MarketplaceDetails"]);
+  });
+
+  it("same name in different namespaces do not conflict", async () => {
+    const oapi = await compileOpenAPI(sameNameInDifferentNamespaces);
+    expect(oapi.definitions).toHaveProperty(["LiftrBase.Widget"]);
+    expect(oapi.definitions).toHaveProperty(["Other.Widget"]);
+  });
+});
+
+describe("name-only", () => {
+  it("removes the namespace from the definition name", async () => {
+    const oapi = await compileOpenAPI(code, { options: { "type-name-strategy": "name-only" } });
+    expect(oapi.definitions).toHaveProperty("MarketplaceDetails");
+    expect(oapi.definitions).not.toHaveProperty(["LiftrBase.MarketplaceDetails"]);
+  });
+
+  it("reports an error when two types collapse to the same name", async () => {
+    const diagnostics = await diagnoseOpenApiFor(sameNameInDifferentNamespaces, {
+      "type-name-strategy": "name-only",
+    });
+
+    expectDiagnostics(diagnostics, [{ code: "@typespec/openapi/duplicate-type-name" }]);
+  });
+
+  it("still honors @friendlyName over the name-only strategy", async () => {
+    const oapi = await compileOpenAPI(
+      `
+      @service
+      namespace MyService;
+
+      namespace LiftrBase {
+        @friendlyName("CustomName")
+        model MarketplaceDetails {}
+      }
+
+      op read(): LiftrBase.MarketplaceDetails;
+      `,
+      { options: { "type-name-strategy": "name-only" } },
+    );
+    expect(oapi.definitions).toHaveProperty("CustomName");
+  });
+});

website/src/content/docs/docs/emitters/typespec-autorest/reference/emitter.md

@@ -193,3 +193,11 @@ Determines whether output should be split into multiple files. The only supporte
 **Default:** `false`
 
 When enabled, the emitter will not copy example files to the output directory. Instead, it will reference the source example files using relative file paths.
+
+### `type-name-strategy`
+
+**Type:** `"namespaced" | "name-only"`
+
+**Default:** `"namespaced"`
+
+Strategy for naming the OpenAPI names derived from TypeSpec types. "namespaced" (default) includes the namespace prefix for types outside the service namespace (e.g. `LiftrBase.Foo`). "name-only" uses only the type name without any namespace prefix (e.g. `Foo`), reporting an error when two types collapse to the same name.