feat: allow zod discriminatedUnion generation (#3698)

Author: titivermeesch

docs/content/docs/guides/zod.mdx

@@ -189,7 +189,7 @@ export default defineConfig({
 
 Per-operation and per-tag overrides accept the settings that apply to an individual schema: `strict`, `generate`, `coerce`, `preprocess`, `params`, and `useBrandedTypes`.
 
-Output-wide settings — `variant`, `version`, `dateTimeOptions`, `timeOptions`, `generateEachHttpStatus`, `generateReusableSchemas`, and `generateMeta` — only make sense for the whole output and must stay on `override.zod`. If you place one on an operation or tag it is ignored — the value from `override.zod` still applies — and Orval prints a build warning:
+Output-wide settings — `variant`, `version`, `dateTimeOptions`, `timeOptions`, `generateEachHttpStatus`, `generateReusableSchemas`, `generateMeta`, and `generateDiscriminatedUnion` — only make sense for the whole output and must stay on `override.zod`. If you place one on an operation or tag it is ignored — the value from `override.zod` still applies — and Orval prints a build warning:
 
 ```
 ⚠️  override.operations.listPets.zod only supports strict, generate, coerce, preprocess, params, and useBrandedTypes. Ignoring unsupported field: zod.version.

docs/content/docs/reference/configuration/output.mdx

@@ -1401,6 +1401,7 @@ export default defineConfig({
           generateEachHttpStatus: true,
           useBrandedTypes: true,
           generateReusableSchemas: true,
+          generateDiscriminatedUnion: true,
         },
       },
     },
@@ -1574,6 +1575,29 @@ Behavior:
 - **zod v3** has no `.meta()` — the option is a no-op there, and descriptions continue to emit via `.describe()`.
 - The registry `id` makes [`z.toJSONSchema()`](https://zod.dev/json-schema) reference the schema as `#/$defs/<id>`, round-tripping the component structure.
 
+### generateDiscriminatedUnion
+
+**Type:** `boolean`
+
+**Default:** `false`
+
+Emit a `oneOf`/`anyOf` that carries an OpenAPI [`discriminator`](https://spec.openapis.org/oas/v3.1.0#discriminator-object) as [`zod.discriminatedUnion(key, [...])`](https://zod.dev/api?id=discriminated-unions) instead of a plain `zod.union([...])`. A discriminated union picks the branch by its discriminator value first, so validation errors point at the offending field (`type.name`) instead of collapsing into a single "no union member matched" at the union root.
+
+```ts
+// override: { zod: { generateDiscriminatedUnion: true } }
+export const Pet = zod.discriminatedUnion('petType', [
+  zod.object({ petType: zod.literal('cat'), meows: zod.boolean() }),
+  zod.object({ petType: zod.literal('dog'), barks: zod.boolean() }),
+]);
+```
+
+Behavior:
+
+- **Opt-in.** Left `false`, unions are emitted exactly as before, so existing output is unchanged.
+- **Safe fallback.** A discriminated union is emitted only when every branch can be represented as an object carrying a literal (`const`/`enum`) discriminator. If any branch is a non-object, a nested union, or lacks a literal discriminator, generation falls back to a plain `zod.union([...])` rather than emitting code that throws at construction.
+- **Inheritance (`allOf`).** Branches composed with `allOf` are flattened into a single object so they remain valid discriminated-union options — this is the case that previously forced the feature to be reverted ([#2085](https://github.com/orval-labs/orval/issues/2085)). With [`generateReusableSchemas`](#generatereusableschemas), a branch that references an `allOf` schema stays a plain union (the referenced schema can't be guaranteed to be an object from the reference alone).
+- Works with both Zod v3 (>= 3.20) and v4, and with the [`mini`](#variant) variant.
+
 ---
 
 ## override.effect

packages/angular/src/http-client.test.ts

@@ -100,6 +100,7 @@ const createOutput = (
         generateEachHttpStatus: false,
         generateReusableSchemas: false,
         generateMeta: false,
+        generateDiscriminatedUnion: false,
         useBrandedTypes: false,
         dateTimeOptions: {},
         timeOptions: {},

packages/angular/src/http-resource.test.ts

@@ -111,6 +111,7 @@ const createOutput = (
         useBrandedTypes: false,
         generateReusableSchemas: false,
         generateMeta: false,
+        generateDiscriminatedUnion: false,
         dateTimeOptions: {},
         timeOptions: {},
       },

packages/core/src/test-utils/context.ts

@@ -132,6 +132,7 @@ export function createTestContextSpec({
         useBrandedTypes: false,
         generateReusableSchemas: false,
         generateMeta: false,
+        generateDiscriminatedUnion: false,
         dateTimeOptions: {},
         timeOptions: { precision: 3 },
       },

packages/core/src/types.ts

@@ -884,6 +884,14 @@ export interface ZodOptions extends BaseZodOptions {
    * via `.describe()`. Default `false`.
    */
   generateMeta?: boolean;
+  /**
+   * When true, a `oneOf`/`anyOf` that carries an OpenAPI `discriminator` is
+   * emitted as `zod.discriminatedUnion(key, [...])` (better per-branch errors)
+   * instead of a plain `zod.union([...])`, but only when every branch can be
+   * represented as an object — otherwise it safely falls back to a union.
+   * Default `false` (opt-in), so existing output is unchanged.
+   */
+  generateDiscriminatedUnion?: boolean;
 }
 
 /**
@@ -948,6 +956,7 @@ export interface NormalizedZodOptions {
   useBrandedTypes: boolean;
   generateReusableSchemas: boolean;
   generateMeta: boolean;
+  generateDiscriminatedUnion: boolean;
   dateTimeOptions: ZodDateTimeOptions;
   timeOptions: ZodTimeOptions;
 }

packages/mock/src/faker/getters/combine.test.ts

@@ -128,6 +128,7 @@ function createMockContext(): ContextSpec {
           useBrandedTypes: false,
           generateReusableSchemas: false,
           generateMeta: false,
+          generateDiscriminatedUnion: false,
           dateTimeOptions: {},
           timeOptions: { precision: 3 },
         },

packages/orval/src/utils/options.ts

@@ -657,6 +657,8 @@ export async function normalizeOptions(
           generateReusableSchemas:
             outputOptions.override?.zod?.generateReusableSchemas ?? false,
           generateMeta: outputOptions.override?.zod?.generateMeta ?? false,
+          generateDiscriminatedUnion:
+            outputOptions.override?.zod?.generateDiscriminatedUnion ?? false,
           dateTimeOptions: outputOptions.override?.zod?.dateTimeOptions ?? {
             offset: true,
           },
@@ -993,6 +995,7 @@ function normalizeOperationsAndTags(
     'generateEachHttpStatus',
     'generateReusableSchemas',
     'generateMeta',
+    'generateDiscriminatedUnion',
   ] as const;
 
   return Object.fromEntries(

packages/solid-start/src/index.test.ts

@@ -133,6 +133,7 @@ function makeOutput(useDates = false): ContextSpec['output'] {
         useBrandedTypes: false,
         generateReusableSchemas: false,
         generateMeta: false,
+        generateDiscriminatedUnion: false,
         dateTimeOptions: {},
         timeOptions: { precision: 3 },
       },