Chapter 54: Zod Mini — API Reference

Core Idea

ZodMiniType (extending zod/v4/core's $ZodType) implements a smaller surface than full Zod's ZodType, but keeps the essentials: parsing methods, .check() for attaching checks, .register(), .brand(), and .clone() — plus, notably, no auto-loaded locale.

Key Concepts

• Parsing methods are identical to Zod: .parse(), .parseAsync(), .safeParse(), .safeParseAsync() all work the same way.
• .check(...): the single mechanism for attaching checks in Mini, replacing all of Zod's individual chained methods (.min(), .refine(), .trim(), etc.). Every check function is type-safe — TypeScript rejects checks that don't apply to the schema's type.
• Check function catalog: numeric/size comparisons (z.lt, z.lte/z.maximum, z.gt, z.gte/z.minimum, z.positive, z.negative, z.nonpositive, z.nonnegative, z.multipleOf), length/size checks (z.maxSize, z.minSize, z.size, z.maxLength, z.minLength, z.length), string checks (z.regex, z.lowercase, z.uppercase, z.includes, z.startsWith, z.endsWith), structural (z.property, z.mime), custom (z.refine, z.check — the Mini replacement for .superRefine()), mutations that don't change the inferred type (z.overwrite, z.normalize, z.trim, z.toLowerCase, z.toUpperCase), and metadata (z.meta, z.describe).
• .register(registry, meta): same registry-registration mechanism as full Zod.
• .brand(tag): same branded-type mechanism as full Zod, just as a function-style call.
• .clone(def): returns a new schema built from a given def object — useful for low-level schema manipulation.
• No default locale: unlike full Zod (which auto-loads en), Zod Mini loads no locale by default, so every issue's message is the generic "Invalid input" unless you explicitly configure a locale via z.config().

Code Examples

import * as z from "zod/mini";

const mySchema = z.string();
mySchema.parse("asdf");
await mySchema.safeParseAsync("asdf");

z.string().check(
  z.minLength(5),
  z.maxLength(10),
  z.refine(val => val.includes("@")),
  z.trim(),
);

const myReg = z.registry<{ title: string }>();
z.string().register(myReg, { title: "My cool string schema" });

const USD = z.string().brand("USD");

const mySchema2 = z.string();
mySchema2.clone(mySchema2._zod.def);

• What it demonstrates: the full shape of Mini's .check()-centric API alongside its other retained instance methods.

Anti-patterns

• Assuming Zod Mini error messages are localized/descriptive by default: without an explicit z.config(en()) (or another locale), every message is the generic "Invalid input" — don't skip locale setup and then be surprised by uninformative errors.

Key Takeaways

1. .check() is Mini's universal attachment point — think of it as replacing the entire family of Zod's chained validation methods.
2. Every check function is a plain, tree-shakable export — only the ones actually imported/used end up in the bundle.
3. Explicitly load a locale in Zod Mini if you want real error messages — it's not automatic like in full Zod.

Connects To

• Zod Mini — Overview & When to Use It: the bundle-size rationale behind this function-based API design.
• Global Error Customization, Internationalization & Precedence: loading a locale, needed explicitly in Mini.