The Check System is Zod's internal mechanism for performing constraint validation on schema values. After a value passes basic type checking, checks verify that it meets additional requirements like minimum/maximum bounds, string format patterns, or custom validation logic. This document explains how checks are defined, attached to schemas, executed during validation, and how they report issues.
For information about the broader validation pipeline, see Validation Pipeline. For information about error handling and issue generation, see Error Handling System.
A check in Zod is any object that implements the $ZodCheck interface. This interface defines the contract between the validation pipeline and individual constraint validators.
Sources: packages/zod/src/v4/core/checks.ts10-39
The $ZodCheckDef interface (packages/zod/src/v4/core/checks.ts11-18) defines the static configuration of a check:
| Property | Type | Purpose |
|---|---|---|
check | string | Identifies the check type (e.g., "less_than", "string_format") |
error | $ZodErrorMap | undefined | Custom error message generator for this check |
abort | boolean | undefined | If true, stops validation after this check fails. Default false |
when | Function | undefined | Conditional execution predicate. Check runs only if this returns true |
The $ZodCheckInternals<T> interface (packages/zod/src/v4/core/checks.ts20-26) adds runtime behavior:
check(payload: ParsePayload<T>) - The validation function that examines the payload and adds issues if validation failsonattach: Function[] - Callbacks executed when the check is attached to a schema, used to update schema metadataissc - The set of issue types this check can produceSources: packages/zod/src/v4/core/checks.ts10-39
Checks progress through three phases: construction, attachment, and execution.
Sources: packages/zod/src/v4/core/schemas.ts185-315
Checks are created via factory functions (typically in the Classic or Mini API layers). These functions instantiate check objects with the appropriate definition:
Sources: packages/zod/src/v4/classic/schemas.ts305
When a check is added to a schema (via .check(), .with(), or schema methods like .min()), the check is appended to def.checks array and its onattach callbacks are executed. These callbacks typically update the schema's metadata bag with constraint information:
This metadata is later used by JSON Schema conversion and other introspection tools.
Sources: packages/zod/src/v4/core/schemas.ts192-203 packages/zod/src/v4/core/checks.ts70-77
During validation, checks are executed by the inst._zod.run() method (packages/zod/src/v4/core/schemas.ts273-299):
forward or backward)when predicate is evaluated (if present)check(payload) method is calledpayload.issues, validation may abort based on the abort flagSources: packages/zod/src/v4/core/schemas.ts213-299
The detailed execution logic handles both synchronous and asynchronous checks, abort flags, and conditional execution.
Sources: packages/zod/src/v4/core/schemas.ts213-255
Key execution behaviors:
isAborted flag tracks whether validation should stop. It's set when issues are added and checked before each subsequent check (packages/zod/src/v4/core/schemas.ts218-246)when predicate allows checks to be skipped based on runtime conditions (packages/zod/src/v4/core/schemas.ts222-228)Sources: packages/zod/src/v4/core/schemas.ts213-255
Zod provides numerous built-in check implementations for common validation patterns.
Sources: packages/zod/src/v4/core/checks.ts44-372
Validates that a numeric value (number, bigint, or Date) is less than or equal to a maximum value. The inclusive flag determines whether the bound is inclusive or exclusive.
Definition: packages/zod/src/v4/core/checks.ts44-95
On attach: Updates bag.maximum or bag.exclusiveMaximum with the constraint value.
Issues produced: $ZodIssueTooBig with code: "too_big".
Validates that a numeric value is greater than or equal to a minimum value.
Definition: packages/zod/src/v4/core/checks.ts97-146
On attach: Updates bag.minimum or bag.exclusiveMinimum.
Issues produced: $ZodIssueTooSmall with code: "too_small".
Validates that a number or bigint is a multiple of a given divisor.
Definition: packages/zod/src/v4/core/checks.ts148-194
Uses util.floatSafeRemainder() for floating-point safe modulo operations.
Issues produced: $ZodIssueNotMultipleOf with code: "not_multiple_of".
Sources: packages/zod/src/v4/core/checks.ts44-194
Sources: packages/zod/src/v4/core/checks.ts389-773
Validate string length against minimum or maximum bounds.
Definition: packages/zod/src/v4/core/checks.ts389-476
On attach: Updates bag.minimum or bag.maximum.
Issues produced: $ZodIssueTooSmall or $ZodIssueTooBig with origin: "string".
Validates strings against a format pattern (email, URL, UUID, etc.). This check is used by specialized schema types like $ZodEmail, $ZodUUID, etc.
Definition: packages/zod/src/v4/core/checks.ts567-650
On attach: Updates bag.format and bag.patterns set.
Issues produced: $ZodIssueInvalidFormat with the specific format name.
The check method first validates against the pattern (if present), then may perform additional validation logic specific to the format.
Sources: packages/zod/src/v4/core/checks.ts567-650
Transform checks modify the input value while validating. They inherit from the check interface but also mutate payload.value.
Sources: packages/zod/src/v4/core/checks.ts729-851
These checks typically don't produce issues themselves but transform the value for subsequent checks.
Beyond built-in checks, Zod supports custom validation logic through several mechanisms.
The .check() method accepts a function that receives a ParsePayload and adds issues as needed:
Sources: packages/zod/src/v4/classic/schemas.ts171-185
The refinement check wraps user-provided validation functions and integrates them into the check system.
Definition: packages/zod/src/v4/core/checks.ts853-942
The refinement function can:
false or throw to indicate failurectx.addIssue() for custom error messagesIssues produced: $ZodIssueCustom with user-specified message and params.
Super refinements provide direct access to the refinement context for advanced validation scenarios:
Definition: packages/zod/src/v4/core/checks.ts944-1004
The refinement context provides:
ctx.addIssue(issue) - Add validation issuesctx.path - Current path in object treeParsePayloadSources: packages/zod/src/v4/core/checks.ts853-1004
Checks report validation failures by appending issue objects to payload.issues.
Sources: packages/zod/src/v4/core/checks.ts79-92
When a check fails, it pushes an issue object following this pattern:
The continue property (derived from !def.abort) controls validation flow:
continue: true (default): Validation continues, collecting all errorscontinue: false: Validation stops immediately after this issueExample from tests:
Sources: packages/zod/src/v4/classic/tests/validations.test.ts45-62
Different schema types use checks differently. String and number schemas use checks extensively, while object and array schemas primarily use checks for size constraints.
String schemas compose multiple check types:
Sources: packages/zod/src/v4/core/schemas.ts326-372
Number schemas support numeric constraint checks:
Sources: packages/zod/src/v4/core/schemas.ts1067-1126
Array, Set, and Map schemas use length/size checks:
Sources: packages/zod/src/v4/classic/tests/array.test.ts9-40 packages/zod/src/v4/classic/tests/set.test.ts7-11
The check system is designed for efficiency while maintaining flexibility.
Checks execute in the order they're attached to the schema. For optimal performance:
abort flag to short-circuit on critical failureswhen predicates to skip unnecessary checksThe onattach callbacks update the schema's metadata bag, which is used by:
This metadata is computed once during schema construction rather than during each validation.
Async checks trigger promise chaining for all subsequent checks (packages/zod/src/v4/core/schemas.ts235-252):
This ensures async checks don't block subsequent synchronous checks unnecessarily.
Sources: packages/zod/src/v4/core/schemas.ts213-299
The Check System provides Zod's constraint validation layer through:
| Component | Purpose | Key Files |
|---|---|---|
$ZodCheck interface | Defines check contract | checks.ts28-30 |
$ZodCheckDef | Static check configuration | checks.ts11-18 |
| Built-in check types | Numeric, string, format validation | checks.ts44-1004 |
onattach callbacks | Update schema metadata | schemas.ts199-202 |
run() method | Execute checks during validation | schemas.ts273-299 |
| Issue reporting | Append validation failures to payload | checks.ts79-92 |
Checks integrate seamlessly with the validation pipeline, providing extensible constraint validation while maintaining performance through careful ordering, abort flags, and conditional execution.
Sources: packages/zod/src/v4/core/checks.ts1-1004 packages/zod/src/v4/core/schemas.ts185-315
Refresh this wiki