Mini API (zod/mini)

Relevant source files

• .devcontainer/devcontainer.json
• CONTRIBUTING.md
• packages/docs/app/llms.txt/route.ts
• packages/docs/content/api.mdx
• packages/docs/content/basics.mdx
• packages/docs/content/ecosystem.mdx
• packages/docs/content/error-formatting.mdx
• packages/docs/content/index.mdx
• packages/docs/content/metadata.mdx
• packages/docs/content/packages/mini.mdx
• packages/docs/content/packages/zod.mdx
• packages/docs/content/v4/changelog.mdx
• packages/docs/content/v4/index.mdx
• packages/docs/content/v4/versioning.mdx
• packages/zod/README.md
• packages/zod/src/v4/classic/schemas.ts
• packages/zod/src/v4/core/api.ts
• packages/zod/src/v4/core/schemas.ts
• packages/zod/src/v4/mini/schemas.ts
• play.ts

Purpose and Scope

This document covers the Zod Mini API (zod/mini), a tree-shakable, functional variant of Zod introduced in v4. Zod Mini provides identical validation functionality to the Classic API but uses a functional programming style that enables significantly better dead-code elimination by modern bundlers.

For information about the standard method-chaining API, see Classic API (zod). For low-level primitives shared by both APIs, see Core Package (zod/v4/core).

Sources: packages/docs/content/packages/mini.mdx1-11 packages/zod/package.json38-95

---

Import Path

Zod Mini is available via the zod/mini export:

The Mini API can also be accessed via zod/v4/mini, which is functionally identical:

Sources: packages/zod/package.json60-64 packages/zod/package.json90-94

---

Functional vs Method-Chaining APIs

The primary difference between Zod Mini and Zod Classic is the programming paradigm: Mini uses functions where Classic uses methods.

Code Architecture Comparison

Diagram: Classic vs Mini API Patterns

Classic API (method chaining):

Mini API (functional composition):

The functional approach allows bundlers to eliminate unused functions, whereas method implementations cannot be tree-shaken even if never called. All methods in packages/zod/src/v4/classic/schemas.ts156-259 are bundled regardless of usage, while functions in packages/zod/src/v4/mini/index.ts are only included when imported.

Sources: packages/docs/content/packages/mini.mdx25-47 packages/zod/src/v4/classic/schemas.ts156-259 packages/zod/src/v4/mini/schemas.ts43-79

---

The .check() Method

In Classic Zod, validation constraints are added via dedicated methods like .min(), .max(), .email(). In Mini, these constraints are passed as arguments to the .check() method defined in packages/zod/src/v4/mini/schemas.ts56-69

Syntax

The .check() method accepts either:

• Check function instances created by factory functions (z.minLength(), z.positive(), etc.)
• Raw check functions of type CheckFn<T> from packages/zod/src/v4/core/schemas.ts41

Examples

String validation:

Number validation:

Custom check functions:

The .check() method is type-safe; TypeScript will prevent adding checks incompatible with the schema type. Check instances are stored in the schema's def.checks array as defined in packages/zod/src/v4/core/schemas.ts88

Sources: packages/docs/content/packages/mini.mdx131-198 packages/zod/src/v4/mini/schemas.ts56-69 packages/zod/src/v4/core/schemas.ts41 packages/zod/src/v4/core/schemas.ts88

---

Available Check Functions

Zod Mini exports a comprehensive set of validation functions. These functions return check objects that can be passed to .check().

Check Function Taxonomy

Numeric Checks

Applied to number and bigint schemas:

• z.lt(value) - less than
• z.lte(value) / z.maximum(value) - less than or equal
• z.gt(value) - greater than
• z.gte(value) / z.minimum(value) - greater than or equal
• z.positive() - greater than 0
• z.negative() - less than 0
• z.nonpositive() - less than or equal to 0
• z.nonnegative() - greater than or equal to 0
• z.multipleOf(value) - divisible by value

Size Checks

Applied to collections (array, set, map) and file schemas:

• z.maxSize(value) - maximum size
• z.minSize(value) - minimum size
• z.size(value) - exact size

Length Checks

Applied to string and array schemas:

• z.maxLength(value) - maximum length
• z.minLength(value) - minimum length
• z.length(value) - exact length

String Format Checks

Applied to string schemas:

• z.regex(pattern) - matches regular expression
• z.lowercase() - validates all lowercase
• z.uppercase() - validates all uppercase
• z.includes(value) - contains substring
• z.startsWith(value) - starts with substring
• z.endsWith(value) - ends with substring

Custom Validation

• z.refine(fn) - custom validation function
• z.check(fn) - replaces .superRefine() from Classic API

Mutations

These modify data during validation but do not change inferred types:

• z.overwrite(fn) - transforms value
• z.normalize() - Unicode normalization
• z.trim() - removes whitespace
• z.toLowerCase() - converts to lowercase
• z.toUpperCase() - converts to uppercase

Metadata

Register schema metadata in z.globalRegistry:

• z.meta(metadata) - register metadata object
• z.describe(description) - register description string

Other Checks

• z.property(key, schema) - validates object property
• z.mime(value) - validates file MIME type

Sources: packages/docs/content/packages/mini.mdx156-198

---

ZodMiniType Base Class

All Zod Mini schemas extend the ZodMiniType base class defined in packages/zod/src/v4/mini/schemas.ts7-38 which provides a minimal but powerful set of methods.

Inheritance Hierarchy

Diagram: Mini API Class Hierarchy

Interface Definition

The ZodMiniType interface extends $ZodType with these methods:

Method Implementations

Parsing Methods

Defined in packages/zod/src/v4/mini/schemas.ts52-55:

Validation Methods

Defined in packages/zod/src/v4/mini/schemas.ts56-70:

Registry Methods

Utility Methods

• inst.clone = (_def, params) => core.clone(inst, _def, params); - line 71
• inst.brand = () => inst as any; - line 72
• inst.apply = (fn) => fn(inst); - line 77

Sources: packages/zod/src/v4/mini/schemas.ts7-79 packages/zod/src/v4/core/schemas.ts174-315

---

Bundle Size Impact

Zod Mini achieves significant bundle size reductions through aggressive tree-shaking.

Bundle Size Comparison

Schema Complexity	Zod Mini (gzip)	Zod Classic (gzip)	Reduction
Boolean parsing	2.12kb	5.91kb	64%
Object with primitives	4.0kb	13.1kb	69%

Bundle Size Analysis

Why Tree-Shaking Works

1. Functions vs Methods: Bundlers can eliminate unused top-level functions but not unused class methods
2. No Default Locale: Classic loads English locale automatically; Mini does not
3. Selective Imports: Only imported validation functions are bundled

When Bundle Size Matters

The 5-10kb difference is meaningful primarily for:

• Mobile-first applications targeting slow 3G networks
• Applications serving users in developing regions
• Highly optimized edge functions with strict size limits
• Libraries where Zod is a transitive dependency

Sources: packages/docs/content/packages/mini.mdx36-80

---

No Default Locale

Unlike Classic Zod, Mini does not automatically load the English locale. All validation errors default to "Invalid input".

Loading a Locale

To enable localized error messages:

This configuration applies globally to all schemas.

Available Locales

Zod provides 40+ language locales via the zod/v4/locales export. The locale system is shared between Classic and Mini APIs.

For complete locale documentation, see Error Customization and Internationalization.

Sources: packages/docs/content/packages/mini.mdx231-244 packages/zod/package.json102-107

---

When to Use Zod Mini

Use Zod Mini When:

1. Bundle Size is Critical: Mobile applications, edge functions, or environments with strict size constraints
2. Targeting Slow Networks: Applications serving users on 2G/3G connections in developing regions
3. Custom Error Handling: Error messages are fully customized or not user-facing
4. Non-English Locales Only: The English locale won't be used

Use Classic Zod When:

1. Backend Development: Bundle size is irrelevant for Node.js applications
2. Developer Experience Matters: Method chaining is more discoverable and ergonomic
3. Rapid Prototyping: Autocomplete and chainable APIs accelerate development
4. Lambda/Serverless: Even at 17kb gzipped, Zod adds <1ms to cold start time

Performance Considerations

Decision Matrix

Factor	Classic	Mini
Bundle size	~13-17kb	~4-6kb
DX (discoverability)	Excellent	Good
DX (verbosity)	Low	Higher
Tree-shaking	Minimal	Excellent
Backend use	Ideal	Overkill
Frontend use	Default choice	Size-constrained
Mobile 3G	Adequate	Preferred

Sources: packages/docs/content/packages/mini.mdx82-109

---

Relationship to Core Package

Zod Mini builds on the zod/v4/core package, which provides low-level primitives shared by both Classic and Mini APIs.

Architecture

Diagram: Core, Mini, and Classic Layering

Key Differences from Core

Feature	Core Package	Zod Mini
Base class	$ZodType schemas.ts174-184	ZodMiniType extends $ZodType mini/schemas.ts7-38
API style	Constructor system only	Functional API + .check()
Schema creation	new $ZodString.init()	z.string() mini/index.ts
Parsing	parse(schema, data) parse.ts15	schema.parse(data) mini/schemas.ts52
Checks	$ZodCheck interface checks.ts22	Check factory functions mini/checks.ts
Error handling	$ZodError class errors.ts296	Same, re-exported
Locales	Not included	Must be loaded via z.config()

Shared Internals

Both Mini and Classic schemas contain a ._zod property defined in packages/zod/src/v4/core/schemas.ts91-161:

The _zod.def property stores the schema definition:

For details on the core architecture, see Core Package (zod/v4/core).

Sources: packages/zod/src/v4/core/schemas.ts91-161 packages/zod/src/v4/mini/schemas.ts7-79 packages/zod/src/v4/classic/schemas.ts20-259 packages/docs/content/packages/core.mdx9-38

---

API Surface Reference

Schema Constructors

Schema Wrappers

Parsing Functions

Configuration

Registries

Sources: packages/zod/package.json60-64 packages/docs/content/packages/mini.mdx14-23