Discriminated union v2

.chronus/changes/discriminated-union-v2-2025-1-19-20-47-47-2.md

@@ -0,0 +1,8 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: feature
+packages:
+  - "@typespec/compiler"
+---
+
+Add new `@discriminated` decorator to represent discriminated union with implicit envelopes

.chronus/changes/discriminated-union-v2-2025-1-19-20-47-47.md

@@ -0,0 +1,14 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: deprecation
+packages:
+  - "@typespec/compiler"
+---
+
+Deprecate use of `@discriminator` on union. Migrate to `@discriminated`
+
+```diff lang="tsp"
+-@discriminator("type")
++@discriminated(#{envelope: "none", discriminatorPropertyName: "type"})
+union Pet;
+```

.chronus/changes/discriminated-union-v2-2025-1-19-21-9-3.md

@@ -0,0 +1,8 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: feature
+packages:
+  - "@typespec/openapi3"
+---
+
+Add support for new `@disriminated` unions

.chronus/changes/discriminated-union-v2-2025-1-20-13-58-27.md

@@ -0,0 +1,6 @@
+---
+changeKind: internal
+packages:
+  - "@typespec/http-specs"
+---
+

.chronus/changes/discriminated-union-v2-2025-1-20-20-20-31.md

@@ -0,0 +1,6 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: internal
+packages:
+  - "@typespec/emitter-framework"
+---

packages/compiler/generated-defs/TypeSpec.ts

@@ -14,6 +14,12 @@ import type {
   UnionVariant,
 } from "../src/core/index.js";
 
+export interface DiscriminatedOptions {
+  readonly envelope?: "object" | "none";
+  readonly discriminatorPropertyName?: string;
+  readonly envelopePropertyName?: string;
+}
+
 export interface ExampleOptions {
   readonly title?: string;
   readonly description?: string;
@@ -567,6 +573,68 @@ export type EncodedNameDecorator = (
   name: string,
 ) => void;
 
+/**
+ * Specify that this union is discriminated.
+ *
+ * @param options Options to configure the serialization of the discriminated union.
+ * @example
+ * ```typespec
+ * @discriminated
+ * union Pet{ cat: Cat, dog: Dog }
+ *
+ * model Cat { meow: boolean }
+ * model Dog { bark: boolean }
+ * ```
+ * Serialized as:
+ * ```json
+ * {
+ *   "kind": "cat",
+ *   "value": {
+ *     "name": "Whiskers",
+ *     "meow": true
+ *   }
+ * },
+ * {
+ *   "kind": "dog",
+ *   "value": {
+ *     "name": "Rex",
+ *     "bark": false
+ *   }
+ * }
+ * ```
+ * @example Custom property names
+ *
+ * ```typespec
+ * @discriminated(#{discriminatorPropertyName: "dataKind", envelopePropertyName: "data"})
+ * union Pet{ cat: Cat, dog: Dog }
+ *
+ * model Cat { meow: boolean }
+ * model Dog { bark: boolean }
+ * ```
+ * Serialized as:
+ * ```json
+ * {
+ *   "dataKind": "cat",
+ *   "data": {
+ *     "name": "Whiskers",
+ *     "meow": true
+ *   }
+ * },
+ * {
+ *   "dataKind": "dog",
+ *   "data": {
+ *     "name": "Rex",
+ *     "bark": false
+ *   }
+ * }
+ * ```
+ */
+export type DiscriminatedDecorator = (
+  context: DecoratorContext,
+  target: Union,
+  options?: DiscriminatedOptions,
+) => void;
+
 /**
  * Specify the property to be used to discriminate this type.
  *
@@ -1089,6 +1157,7 @@ export type TypeSpecDecorators = {
   overload: OverloadDecorator;
   projectedName: ProjectedNameDecorator;
   encodedName: EncodedNameDecorator;
+  discriminated: DiscriminatedDecorator;
   discriminator: DiscriminatorDecorator;
   example: ExampleDecorator;
   opExample: OpExampleDecorator;

packages/compiler/lib/std/decorators.tsp

@@ -391,6 +391,83 @@ extern dec projectedName(
  */
 extern dec encodedName(target: unknown, mimeType: valueof string, name: valueof string);
 
+/**
+ * Options for `@discriminated` decorator.
+ */
+model DiscriminatedOptions {
+  /**
+   * How is the discriminated union serialized.
+   * @default object
+   */
+  envelope?: "object" | "none";
+
+  /** Name of the discriminator property */
+  discriminatorPropertyName?: string;
+
+  /** Name of the property envelopping the data */
+  envelopePropertyName?: string;
+}
+
+/**
+ * Specify that this union is discriminated.
+ * @param options Options to configure the serialization of the discriminated union.
+ *
+ * @example
+ *
+ * ```typespec
+ * @discriminated
+ * union Pet{ cat: Cat, dog: Dog }
+ *
+ * model Cat { meow: boolean }
+ * model Dog { bark: boolean }
+ * ```
+ * Serialized as:
+ * ```json
+ * {
+ *   "kind": "cat",
+ *   "value": {
+ *     "name": "Whiskers",
+ *     "meow": true
+ *   }
+ * },
+ * {
+ *   "kind": "dog",
+ *   "value": {
+ *     "name": "Rex",
+ *     "bark": false
+ *   }
+ * }
+ * ```
+ *
+ * @example Custom property names
+ *
+ * ```typespec
+ * @discriminated(#{discriminatorPropertyName: "dataKind", envelopePropertyName: "data"})
+ * union Pet{ cat: Cat, dog: Dog }
+ *
+ * model Cat { meow: boolean }
+ * model Dog { bark: boolean }
+ * ```
+ * Serialized as:
+ * ```json
+ * {
+ *   "dataKind": "cat",
+ *   "data": {
+ *     "name": "Whiskers",
+ *     "meow": true
+ *   }
+ * },
+ * {
+ *   "dataKind": "dog",
+ *   "data": {
+ *     "name": "Rex",
+ *     "bark": false
+ *   }
+ * }
+ * ```
+ */
+extern dec discriminated(target: Union, options?: valueof DiscriminatedOptions);
+
 /**
  * Specify the property to be used to discriminate this type.
  * @param propertyName The property name to use for discrimination