feat: add option to inject params in generated zod schemas

Author: titivermeesch

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

@@ -1080,6 +1080,67 @@ Control which schemas are generated.
 
 Add preprocess functions to schemas.
 
+### params
+
+**Type:** [`Mutator`](#mutator)
+
+Inject a Zod `params` argument (e.g. `{ error: ... }`) into every generated validator. The referenced function is called once per validator at schema construction time and receives codegen-time context (operation, location, schema name, field path, validator name). Whatever it returns is passed as the trailing argument of the call.
+
+Useful for i18n error keys, branded error messages, or any field-aware customisation that Zod's global error map cannot disambiguate on its own (because `issue.path` does not carry operation/schema identity).
+
+```ts title="orval.config.ts"
+export default defineConfig({
+  petstore: {
+    output: {
+      override: {
+        zod: {
+          params: { path: './zod-params.ts', name: 'zodParams' },
+        },
+      },
+    },
+  },
+});
+```
+
+```ts title="zod-params.ts"
+import { i18n } from './i18n';
+
+type ZodParamsContext = {
+  operationId: string;
+  location: 'param' | 'query' | 'header' | 'body' | 'response';
+  schemaName: string;
+  fieldPath: string[];
+  validator: string;
+};
+
+export const zodParams = (ctx: ZodParamsContext) => ({
+  error: (issue: { input: unknown; path: PropertyKey[] }) =>
+    i18n.t(
+      `errors.${ctx.schemaName}.${ctx.fieldPath.join('.')}.${ctx.validator}`,
+      { value: issue.input },
+    ),
+});
+```
+
+Generated output (excerpt):
+
+```ts
+import { zodParams } from './zod-params';
+
+export const CreateUserBody = zod.object({
+  email: zod
+    .string(zodParams({ operationId: 'createUser', location: 'body', schemaName: 'CreateUserBody', fieldPath: ['email'], validator: 'string' }))
+    .email(zodParams({ operationId: 'createUser', location: 'body', schemaName: 'CreateUserBody', fieldPath: ['email'], validator: 'email' })),
+});
+```
+
+Injection scope:
+
+- Applied to base types (`string`, `number`, `boolean`, `bigint`, `date`, `integer`), constraints (`min`, `max`, `gt`, `lt`, `multipleOf`, `regex`, `length`), formats (`email`, `url`, `uuid`, `hostname`, `datetime`, `time`), and `literal`, `enum`, `instanceof`, `stringFormat`.
+- Skipped on modifiers (`optional`, `nullable`, `nullish`, `default`, `describe`) and structural calls (`object`, `array`, `tuple`, `union`, `rest`, `passthrough`, `strict`).
+
+Static messages are supported by returning a plain string: `return { error: 'My message' }`. The function may return `undefined` to fall back to Zod defaults for a specific call.
+
 ### dateTimeOptions / timeOptions
 
 **Type:** `Object`

packages/core/src/types.ts

@@ -743,6 +743,13 @@ export interface ZodOptions {
     body?: Mutator;
     response?: Mutator;
   };
+  /**
+   * Mutator referencing a function called once per emitted validator at schema
+   * construction time. It receives codegen-time context (operation, location,
+   * schema name, field path, validator name) and returns a Zod `params` object
+   * (e.g. `{ error: ... }`) that is appended as the trailing argument.
+   */
+  params?: Mutator;
   dateTimeOptions?: ZodDateTimeOptions;
   timeOptions?: ZodTimeOptions;
   generateEachHttpStatus?: boolean;
@@ -793,6 +800,7 @@ export interface NormalizedZodOptions {
     body?: NormalizedMutator;
     response?: NormalizedMutator;
   };
+  params?: NormalizedMutator;
   generateEachHttpStatus: boolean;
   useBrandedTypes: boolean;
   generateReusableSchemas: boolean;

packages/orval/src/utils/options.ts

@@ -504,6 +504,14 @@ export async function normalizeOptions(
                 }
               : {}),
           },
+          ...(outputOptions.override?.zod?.params
+            ? {
+                params: normalizeMutator(
+                  workspace,
+                  outputOptions.override.zod.params,
+                ),
+              }
+            : {}),
           generateEachHttpStatus:
             outputOptions.override?.zod?.generateEachHttpStatus ?? false,
           useBrandedTypes:
@@ -890,6 +898,11 @@ function normalizeOperationsAndTags(
                           }
                         : {}),
                     },
+                    ...(zod.params
+                      ? {
+                          params: normalizeMutator(workspace, zod.params),
+                        }
+                      : {}),
                     generateEachHttpStatus: zod.generateEachHttpStatus ?? false,
                     useBrandedTypes: zod.useBrandedTypes ?? false,
                     generateReusableSchemas: