3.25.27. Use for override. Add .value to ZodLiteral.

Author: colinhacks

packages/docs/content/error-customization.mdx

@@ -181,14 +181,14 @@ z.string().min(5, {
 Return `undefined` to avoid setting an error message. This is useful for customizing certain error messages but not others. Zod will yield control to the next error map in the [precedence chain](#error-precedence).
 
 ```ts
-z.string().min(5, {
-  error: (iss) => {
-    // customize "too_small" error message
-    if (iss.code === "too_small") {
-      return `Password must have ${iss.minimum} characters or more`;
+z.int64({
+  error: (issue) => {
+    // override too_big error message
+    if (issue.code === "too_big") {
+      return { message: `Value must be <${issue.maximum}` };
     }
 
-    // use default error otherwise
+    //  defer to default
     return undefined;
   },
 });

packages/docs/content/json-schema.mdx

@@ -414,6 +414,7 @@ z.toJSONSchema(mySchema, {
 });
 ```
 
+Note that unrepresentable types will throw an `Error` before this functions is called. If you are trying to define custom behavior for an unrepresentable type, you'll need to use set the `unrepresentable: "any"` alongside `override`.
 
 ### `io`
 

packages/zod/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zod",
-  "version": "3.25.26",
+  "version": "3.25.27",
   "type": "module",
   "author": "Colin McDonnell <[email protected]>",
   "description": "TypeScript-first schema declaration and validation library with static type inference",

packages/zod/src/v4/classic/schemas.ts

@@ -1540,11 +1540,21 @@ export function nativeEnum<T extends util.EnumLike>(entries: T, params?: string
 export interface ZodLiteral<T extends util.Primitive = util.Primitive> extends ZodType {
   _zod: core.$ZodLiteralInternals<T>;
   values: Set<T>;
+  /** @legacy Use `.values` instead. Accessing this property will throw an error if the literal accepts multiple values. */
+  value: T;
 }
 export const ZodLiteral: core.$constructor<ZodLiteral> = /*@__PURE__*/ core.$constructor("ZodLiteral", (inst, def) => {
   core.$ZodLiteral.init(inst, def);
   ZodType.init(inst, def);
   inst.values = new Set(def.values);
+  Object.defineProperty(inst, "value", {
+    get() {
+      if (def.values.length > 1) {
+        throw new Error("This schema contains multiple valid literal values. Use `.values` instead.");
+      }
+      return def.values[0];
+    },
+  });
 });
 
 export function literal<const T extends Array<util.Literal>>(

packages/zod/src/v4/classic/tests/literal.test.ts

@@ -80,3 +80,8 @@ test("literal bigint default error message", () => {
   expect(result.error!.issues.length).toEqual(1);
   expect(result.error!.issues[0].message).toEqual(`Invalid input: expected 12n`);
 });
+
+test(".value getter", () => {
+  expect(z.literal("tuna").value).toEqual("tuna");
+  expect(() => z.literal([1, 2, 3]).value).toThrow();
+});

packages/zod/src/v4/core/schemas.ts

@@ -2777,7 +2777,7 @@ export interface $ZodLiteralDef extends $ZodTypeDef {
 
 export interface $ZodLiteralInternals<T extends util.Primitive = util.Primitive> extends $ZodTypeInternals<T, T> {
   def: $ZodLiteralDef;
-  values: util.PrimitiveSet;
+  values: Set<T>;
   pattern: RegExp;
   isst: errors.$ZodIssueInvalidValue;
 }

packages/zod/src/v4/core/to-json-schema.ts

@@ -16,7 +16,7 @@ interface JSONSchemaGeneratorParams {
    * - `"any"` — Unrepresentable types become `{}` */
   unrepresentable?: "throw" | "any";
   /** Arbitrary custom logic that can be used to modify the generated JSON Schema. */
-  override?: (ctx: { zodSchema: schemas.$ZodType; jsonSchema: JSONSchema.BaseSchema }) => void;
+  override?: (ctx: { zodSchema: schemas.$ZodTypes; jsonSchema: JSONSchema.BaseSchema }) => void;
   /** Whether to extract the `"input"` or `"output"` type. Relevant to transforms, Error converting schema to JSONz, defaults, coerced primitives, etc.
    * - `"output" — Default. Convert the output schema.
    * - `"input"` — Convert the input schema. */
@@ -73,7 +73,7 @@ export class JSONSchemaGenerator {
   metadataRegistry: $ZodRegistry<Record<string, any>>;
   target: "draft-7" | "draft-2020-12";
   unrepresentable: "throw" | "any";
-  override: (ctx: { zodSchema: schemas.$ZodType; jsonSchema: JSONSchema.BaseSchema }) => void;
+  override: (ctx: { zodSchema: schemas.$ZodTypes; jsonSchema: JSONSchema.BaseSchema }) => void;
   io: "input" | "output";
 
   counter = 0;
@@ -694,7 +694,7 @@ export class JSONSchemaGenerator {
 
       if (!seen.isParent)
         this.override({
-          zodSchema,
+          zodSchema: zodSchema as schemas.$ZodTypes,
           jsonSchema: schema,
         });
     };

play.ts

@@ -1,5 +1,3 @@
-import * as z from "zod/v4-mini";
+import * as z from "zod/v4";
 
-z.string().register(z.globalRegistry, {
-  examples: ["example"], // Type 'string' is not assignable to type 'unique symbol'.
-});
+z;