Fix @actionSeparator decorator to accept Operation, Interface, and Namespace targets with hierarchy support (#8609)

## ✅ Fix @actionSeparator decorator target validation and hierarchy
behavior - COMPLETED

Successfully narrowed the `@actionSeparator` decorator targets from
`Model | ModelProperty | Operation` to `Operation | Interface |
Namespace` and implemented proper hierarchy behavior where separators
can be applied at namespace or interface level and automatically
propagate to contained operations.

### ✅ Completed Tasks:
- [x] Analyze current implementation and reproduce the issue
- [x] Verify current tests pass
- [x] Update the TypeScript decorator function signature to accept only
`Operation | Interface | Namespace`
- [x] Update the TypeSpec decorator definition in rest-decorators.tsp to
match
- [x] Update generated TypeScript definitions 
- [x] Add comprehensive validation tests for each allowed target type
- [x] Implement hierarchy lookup logic for namespace and interface
targets
- [x] Add tests for hierarchy and override behavior
- [x] Run tests to ensure no regressions - ALL 64 tests pass ✅
- [x] Update README and website documentation with hierarchy explanation
- [x] Test the fix manually with reproduction case - SUCCESSFUL ✅
- [x] Merge latest changes from main branch
- [x] Add changelog entry using chronus
- [x] Fix formatting issues with pnpm format
- [x] Include generated TypeSpec definitions in PR
- [x] Address code review feedback (backticks, describe blocks,
decorator style)

### ✅ Fix Summary:
**Issue resolved**: `@actionSeparator` now correctly accepts only
`Operation`, `Interface`, and `Namespace` as targets, and properly
rejects `Model` and `ModelProperty` targets. The decorator implements a
hierarchy system where:
- **Namespace-level**: Separator applies to all action operations in the
namespace and its sub-namespaces (recursively)
- **Interface-level**: Separator applies to all action operations in the
interface and overrides namespace-level separators
- **Operation-level**: Separator applies only to that operation and
overrides both interface and namespace-level separators

### ✅ Validation Results:

**1. Target Validation Working Correctly:**
- ✅ `@actionSeparator` on Operations: Works and affects routing
- ✅ `@actionSeparator` on Interfaces: Applies to all operations in
interface
- ✅ `@actionSeparator` on Namespaces: Applies to all operations in
namespace and sub-namespaces
- ✅ `@actionSeparator` on Models: Correctly rejected with proper error
message
- ✅ `@actionSeparator` on ModelProperties: Correctly rejected with
proper error message

**2. Hierarchy Behavior:**
- ✅ Interface-level separator applies to all actions in interface
- ✅ Namespace-level separator applies to all actions in namespace and
sub-namespaces
- ✅ Operation-level separator overrides interface-level separator
- ✅ Interface-level separator overrides namespace-level separator
- ✅ Proper recursive lookup through namespace hierarchy

**3. Functionality Tests:**
- ✅ All separator values (`/`, `:`, `/:`) work correctly in routing
- ✅ Operations with `@actionSeparator` generate correct route paths  
- ✅ Original reproduction case now compiles successfully
- ✅ Invalid usage cases are properly rejected with clear error messages

**4. Regression Tests:**
- ✅ All existing tests continue to pass (64/64 tests pass)
- ✅ No breaking changes to existing functionality
- ✅ Route generation works as expected

### 📁 Files Modified:
- `packages/rest/src/rest.ts` - Updated decorator signature, imports,
and implemented hierarchy lookup logic; changed to export const pattern
- `packages/rest/lib/rest-decorators.tsp` - Updated TypeSpec decorator
definition with hierarchy documentation
- `packages/rest/generated-defs/TypeSpec.Rest.ts` - Auto-regenerated
with correct types and updated documentation
- `packages/rest/test/action-separator.test.ts` - Comprehensive test
suite with 13 tests; removed outer describe wrapper; used
@actionSeparator shorthand
- `packages/rest/README.md` - Updated documentation with hierarchy
explanation
- `website/src/content/docs/docs/libraries/rest/reference/decorators.md`
- Regenerated documentation
-
`.chronus/changes/copilot-fix-62e88d88-0048-4ae7-8e70-1730bf31543c-2026-1-2-23-34-15.md`
- Changelog entry (with backticks)

### 🎯 Impact:
The fix resolves the original issue where `@actionSeparator` was
incorrectly allowing Model and ModelProperty targets that didn't work
properly. Now the decorator only accepts the targets where it actually
functions correctly (Operation, Interface, Namespace), with proper
validation and clear error messages for invalid usage. Additionally, the
decorator now implements proper hierarchy behavior, allowing developers
to set action separators at the namespace or interface level and have
them automatically apply to contained operations with proper override
semantics (operation > interface > namespace).

<!-- START COPILOT CODING AGENT SUFFIX -->



<details>

<summary>Original prompt</summary>

> 
> ----
> 
> *This section details on the original issue you should resolve*
> 
> <issue_title>[Bug]: @actionSerparator works only when defined on
operation, but allowed on models and models properties</issue_title>
> <issue_description>### Describe the bug
> 
> There's no well written documentation on how to use it either, so it
might be that I'm doing it wrong.
> 
> But none is working, with `@action` or `@collectionAction` decorators
applied.
> 
> ### Reproduction
> 
>
https://typespec.io/playground/?e=%40typespec%2Fopenapi3&c=aW1wb3J0ICJAdHlwZXNwZWMvaHR0cCI7CtIZcmVzdCI7Cgp1c2luZyBIdHRwO8cMUmVzdDsKCkBzZXJ2aWNlCm5hbWVzcGFjZSBUxBogCgoKQHJvdXRlKCJvbi1vcCIpyyNPbk9wIHsKICBAYXV0b1LEJ8UNY3Rpb27KClNlcGFyYXRvcigiOiIpCiAgb3AgZG8oKTogdm9pZDsKfc1kbW9kZWzPZ03EFMdq1lPFNiBFbnRpdHnFKSAgaWQ6IHN0cmluZzsKICB9CvEAqGNvbGxlxU9BxQYoxj%2FET8dn%2FwCs5gCsLXByb3BldHn0ALRQxBty5wCT8wCk%2BADP%2FwC%2B%2FwC%2B%2BgC%2B&options=%7B%7D&vs=%7B%7D
> 
> ### Checklist
> 
> - [x] Follow our [Code of
Conduct](https://github.com/microsoft/typespec/blob/main/CODE_OF_CONDUCT.md)
> - [x] Check that there isn't already an issue that request the same
bug to avoid creating a duplicate.
> - [x] Check that this is a concrete bug. For Q&A open a [GitHub
Discussion](https://github.com/Microsoft/typespec/discussions).
> - [x] The provided reproduction is a [minimal reproducible
example](https://stackoverflow.com/help/minimal-reproducible-example) of
the bug.</issue_description>
> 
> <agent_instructions>Narrow the target of the `@actionSeparator` to
include only operations, interfaces, and namespaces. Ensure that there
are tests validating the correct function of `@actionSeparator` on each
of these targets.</agent_instructions>
> 
> ## Comments on the Issue (you are @copilot in this section)
> 
> <comments>
> </comments>
> 


</details>
Fixes #8589

<!-- START COPILOT CODING AGENT TIPS -->
---

✨ Let Copilot coding agent [set things up for
you](https://github.com/microsoft/typespec/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot)
— coding agent works faster and does higher quality work when set up for
your repo.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>

Author: Copilot

.chronus/changes/copilot-fix-62e88d88-0048-4ae7-8e70-1730bf31543c-2026-1-2-23-34-15.md

@@ -0,0 +1,7 @@
+---
+changeKind: fix
+packages:
+  - "@typespec/rest"
+---
+
+Fix `@actionSeparator` decorator to only accept Operation, Interface, and Namespace targets

packages/rest/README.md

@@ -51,13 +51,17 @@ Specify this operation is an action. (Scoped to a resource item /pets/{petId}/my
 
 Defines the separator string that is inserted before the action name in auto-generated routes for actions.
 
+When applied to a namespace, the separator applies to all action operations in that namespace and its sub-namespaces.
+When applied to an interface, the separator applies to all action operations in that interface and overrides any namespace-level separator.
+When applied to an operation, the separator applies only to that operation and overrides any interface or namespace-level separator.
+
 ```typespec
 @TypeSpec.Rest.actionSeparator(seperator: valueof "/" | ":" | "/:")
 ```
 
 ##### Target
 
-`Model | ModelProperty | Operation`
+`Operation | Interface | Namespace`
 
 ##### Parameters
 

packages/rest/generated-defs/TypeSpec.Rest.ts

@@ -4,6 +4,7 @@ import type {
   Interface,
   Model,
   ModelProperty,
+  Namespace,
   Operation,
 } from "@typespec/compiler";
 
@@ -58,11 +59,15 @@ export type SegmentOfDecorator = (
 /**
  * Defines the separator string that is inserted before the action name in auto-generated routes for actions.
  *
+ * When applied to a namespace, the separator applies to all action operations in that namespace and its sub-namespaces.
+ * When applied to an interface, the separator applies to all action operations in that interface and overrides any namespace-level separator.
+ * When applied to an operation, the separator applies only to that operation and overrides any interface or namespace-level separator.
+ *
  * @param seperator Seperator seperating the action segment from the rest of the url
  */
 export type ActionSeparatorDecorator = (
   context: DecoratorContext,
-  target: Model | ModelProperty | Operation,
+  target: Operation | Interface | Namespace,
   seperator: "/" | ":" | "/:",
 ) => DecoratorValidatorCallbacks | void;
 

packages/rest/lib/rest-decorators.tsp

@@ -38,10 +38,14 @@ extern dec segmentOf(target: Operation, type: Model);
 /**
  * Defines the separator string that is inserted before the action name in auto-generated routes for actions.
  *
+ * When applied to a namespace, the separator applies to all action operations in that namespace and its sub-namespaces.
+ * When applied to an interface, the separator applies to all action operations in that interface and overrides any namespace-level separator.
+ * When applied to an operation, the separator applies only to that operation and overrides any interface or namespace-level separator.
+ *
  * @param seperator Seperator seperating the action segment from the rest of the url
  */
 extern dec actionSeparator(
-  target: Model | ModelProperty | Operation,
+  target: Operation | Interface | Namespace,
   seperator: valueof "/" | ":" | "/:"
 );
 

packages/rest/src/rest.ts

@@ -5,6 +5,7 @@ import {
   Interface,
   Model,
   ModelProperty,
+  Namespace,
   Operation,
   Program,
   Scalar,
@@ -32,6 +33,7 @@ import {
 } from "@typespec/http/experimental";
 import {
   ActionDecorator,
+  ActionSeparatorDecorator,
   AutoRouteDecorator,
   CollectionActionDecorator,
   ListsResourceDecorator,
@@ -273,23 +275,77 @@ const actionSeparatorKey = createStateSymbol("actionSeparator");
  * `@actionSeparator` defines the separator string that is used to precede the action name
  *  in auto-generated actions.
  *
- * `@actionSeparator` can only be applied to model properties, operation parameters, or operations.
+ * `@actionSeparator` can only be applied to operations, interfaces, or namespaces.
  */
-export function $actionSeparator(
+export const $actionSeparator: ActionSeparatorDecorator = (
   context: DecoratorContext,
-  entity: Model | ModelProperty | Operation,
+  entity: Operation | Interface | Namespace,
   separator: "/" | ":" | "/:",
-) {
+) => {
   context.program.stateMap(actionSeparatorKey).set(entity, separator);
-}
+};
 
 /**
  * @param program the TypeSpec program
  * @param entity the target entity
- * @returns the action separator string
+ * @returns the action separator string, checking the hierarchy: operation -> interface -> namespace
  */
 export function getActionSeparator(program: Program, entity: Type): string | undefined {
-  return program.stateMap(actionSeparatorKey).get(entity);
+  const stateMap = program.stateMap(actionSeparatorKey);
+
+  // First, check if the entity itself has an action separator
+  const directSeparator = stateMap.get(entity);
+  if (directSeparator !== undefined) {
+    return directSeparator;
+  }
+
+  // If entity is an operation, check its interface, then namespace
+  if (entity.kind === "Operation") {
+    // Check the interface
+    if (entity.interface) {
+      const interfaceSeparator = stateMap.get(entity.interface);
+      if (interfaceSeparator !== undefined) {
+        return interfaceSeparator;
+      }
+
+      // Check the namespace of the interface
+      if (entity.interface.namespace) {
+        return getNamespaceActionSeparator(program, entity.interface.namespace);
+      }
+    }
+
+    // Check the namespace directly if no interface
+    if (entity.namespace) {
+      return getNamespaceActionSeparator(program, entity.namespace);
+    }
+  }
+
+  // If entity is an interface, check its namespace
+  if (entity.kind === "Interface" && entity.namespace) {
+    return getNamespaceActionSeparator(program, entity.namespace);
+  }
+
+  return undefined;
+}
+
+/**
+ * Helper function to recursively check namespace hierarchy for action separator
+ */
+function getNamespaceActionSeparator(program: Program, namespace: Namespace): string | undefined {
+  const stateMap = program.stateMap(actionSeparatorKey);
+
+  // Check current namespace
+  const separator = stateMap.get(namespace);
+  if (separator !== undefined) {
+    return separator;
+  }
+
+  // Check parent namespace recursively
+  if (namespace.namespace) {
+    return getNamespaceActionSeparator(program, namespace.namespace);
+  }
+
+  return undefined;
 }
 
 /**

packages/rest/test/action-separator.test.ts

@@ -0,0 +1,224 @@
+import { expectDiagnostics } from "@typespec/compiler/testing";
+import { strictEqual } from "assert";
+import { describe, it } from "vitest";
+import { Tester, getRoutesFor } from "./test-host.js";
+
+describe("valid targets", () => {
+  it("works on Operation and affects routing", async () => {
+    const routes = await getRoutesFor(`
+      @autoRoute
+      interface Things {
+        @action
+        @actionSeparator(":")
+        @put op customAction(@segment("things") @path thingId: string): string;
+      }
+    `);
+
+    strictEqual(routes.length, 1);
+    strictEqual(routes[0].path, "/things/{thingId}:customAction");
+  });
+
+  it("accepts Interface as target without compilation errors", async () => {
+    // This test verifies that @actionSeparator can be applied to interfaces without errors
+    const diagnostics = await Tester.diagnose(`
+      @actionSeparator(":")
+      interface TestInterface {
+        op test(): void;
+      }
+    `);
+
+    // No diagnostics means the decorator accepts interfaces as valid targets
+    strictEqual(diagnostics.length, 0);
+  });
+
+  it("accepts Namespace as target without compilation errors", async () => {
+    // This test verifies that @actionSeparator can be applied to namespaces without errors
+    const diagnostics = await Tester.diagnose(`
+      @actionSeparator(":")
+      namespace TestNamespace {
+        op test(): void;
+      }
+    `);
+
+    // No diagnostics means the decorator accepts namespaces as valid targets
+    strictEqual(diagnostics.length, 0);
+  });
+
+  it("supports all separator values in routing", async () => {
+    const routes = await getRoutesFor(`
+      @autoRoute
+      interface Things {
+        @action
+        @actionSeparator("/")
+        @put op action1(@segment("things") @path thingId: string): string;
+
+        @action
+        @actionSeparator(":")
+        @put op action2(@segment("things") @path thingId: string): string;
+
+        @action
+        @actionSeparator("/:")
+        @put op action3(@segment("things") @path thingId: string): string;
+      }
+    `);
+
+    strictEqual(routes.length, 3);
+    strictEqual(routes[0].path, "/things/{thingId}/action1");
+    strictEqual(routes[1].path, "/things/{thingId}:action2");
+    strictEqual(routes[2].path, "/things/{thingId}/:action3");
+  });
+});
+
+describe("hierarchy behavior", () => {
+  it("interface-level separator applies to all actions in interface", async () => {
+    const routes = await getRoutesFor(`
+      @autoRoute
+      @actionSeparator(":")
+      interface Things {
+        @action
+        @put op action1(@segment("things") @path thingId: string): string;
+
+        @action
+        @put op action2(@segment("things") @path thingId: string): string;
+      }
+    `);
+
+    strictEqual(routes.length, 2);
+    strictEqual(routes[0].path, "/things/{thingId}:action1");
+    strictEqual(routes[1].path, "/things/{thingId}:action2");
+  });
+
+  it("namespace-level separator applies to all actions in namespace", async () => {
+    const routes = await getRoutesFor(`
+      @actionSeparator(":")
+      namespace TestNs {
+        @autoRoute
+        interface Things {
+          @action
+          @put op action1(@segment("things") @path thingId: string): string;
+        }
+      }
+    `);
+
+    strictEqual(routes.length, 1);
+    strictEqual(routes[0].path, "/things/{thingId}:action1");
+  });
+
+  it("operation-level separator overrides interface-level separator", async () => {
+    const routes = await getRoutesFor(`
+      @autoRoute
+      @actionSeparator(":")
+      interface Things {
+        @action
+        @actionSeparator("/")
+        @put op action1(@segment("things") @path thingId: string): string;
+
+        @action
+        @put op action2(@segment("things") @path thingId: string): string;
+      }
+    `);
+
+    strictEqual(routes.length, 2);
+    strictEqual(routes[0].path, "/things/{thingId}/action1"); // Uses operation-level "/"
+    strictEqual(routes[1].path, "/things/{thingId}:action2"); // Uses interface-level ":"
+  });
+
+  it("interface-level separator overrides namespace-level separator", async () => {
+    const routes = await getRoutesFor(`
+      @actionSeparator("/:")
+      namespace TestNs {
+        @autoRoute
+        @actionSeparator(":")
+        interface Things {
+          @action
+          @put op action1(@segment("things") @path thingId: string): string;
+        }
+        
+        @autoRoute
+        interface Other {
+          @action
+          @put op action2(@segment("other") @path otherId: string): string;
+        }
+      }
+    `);
+
+    strictEqual(routes.length, 2);
+    strictEqual(routes[0].path, "/things/{thingId}:action1"); // Uses interface-level ":"
+    strictEqual(routes[1].path, "/other/{otherId}/:action2"); // Uses namespace-level "/:"
+  });
+
+  it("namespace separator applies to subnamespaces", async () => {
+    const routes = await getRoutesFor(`
+      @actionSeparator(":")
+      namespace Parent {
+        namespace Child {
+          @autoRoute
+          interface Things {
+            @action
+            @put op action1(@segment("things") @path thingId: string): string;
+          }
+        }
+      }
+    `);
+
+    strictEqual(routes.length, 1);
+    strictEqual(routes[0].path, "/things/{thingId}:action1"); // Uses parent namespace-level ":"
+  });
+
+  it("operation in namespace without interface uses namespace separator", async () => {
+    const routes = await getRoutesFor(`
+      @actionSeparator(":")
+      namespace TestNs {
+        @autoRoute
+        @action
+        @put op action1(@segment("things") @path thingId: string): string;
+      }
+    `);
+
+    strictEqual(routes.length, 1);
+    strictEqual(routes[0].path, "/things/{thingId}:action1");
+  });
+});
+
+describe("invalid targets", () => {
+  it("rejects Model", async () => {
+    const diagnostics = await Tester.diagnose(`
+      @actionSeparator(":")
+      model TestModel {
+        id: string;
+      }
+    `);
+
+    expectDiagnostics(diagnostics, {
+      code: "decorator-wrong-target",
+      message:
+        "Cannot apply @actionSeparator decorator to TestModel since it is not assignable to Operation | Interface | Namespace",
+    });
+  });
+
+  it("rejects ModelProperty", async () => {
+    const diagnostics = await Tester.diagnose(`
+      model TestModel {
+        @actionSeparator(":")
+        id: string;
+      }
+    `);
+
+    expectDiagnostics(diagnostics, {
+      code: "decorator-wrong-target",
+      message:
+        /Cannot apply @actionSeparator decorator to .* since it is not assignable to Operation \| Interface \| Namespace/,
+    });
+  });
+
+  it("rejects invalid separator values", async () => {
+    const diagnostics = await Tester.diagnose(`
+      @actionSeparator("invalid")
+      op test(): void;
+    `);
+
+    expectDiagnostics(diagnostics, {
+      code: "invalid-argument",
+    });
+  });
+});