Cross-field validation
A form or API object has related fields whose combined values must satisfy a rule.
Zod · Type Alias
RefinementCtx
RefinementCtx is the context passed to custom refinement callbacks. Use it to record validation issues and associate them with locations in the parsed data.
How it works
RefinementCtx is the context object passed to refinement callbacks. In current Zod, refinement-style callbacks use it to report validation failures by adding issues, including a path that identifies the problematic part of the input.
Syntax
(value, ctx) => { /* use ctx.issues */ }Key points
- The context is relevant when a schema executes custom checks beyond its built-in validation rules.
- Refinement execution can be conditional, so context-dependent issue reporting may not occur for every input.
- Use the more expressive refinement callback when validation needs richer issue reporting than a single custom error.
- A single callback can communicate several independent validation failures.
Common mistakes
- In current Zod, issue reporting uses ctx.issues rather than the older ctx.addIssue pattern shown in legacy documentation.
- Do not throw from refinement logic; report failures through the refinement context instead.
Example: Report a cross-field validation issue
import { z } from "zod";
const User = z.object({
password: z.string(),
confirmPassword: z.string(),
}).superRefine((data, ctx) => {
if (data.password !== data.confirmPassword) {
ctx.addIssue({
code: "custom",
path: ["confirmPassword"],
message: "Passwords do not match",
});
}
});
console.log(User.safeParse({
password: "secret",
confirmPassword: "different",
}).success);Uses the refinement context supplied to superRefine to add a targeted validation issue.
When to use it
Collect multiple validation issues
One input can violate several independent business constraints.
Targeted error paths
An error should point to a nested property rather than the whole object.
Interview questions
QWhat is RefinementCtx used for?
RefinementCtx is the callback context available while custom validation runs. It lets the callback communicate validation failures to Zod by recording issues, including their messages and paths.
Follow-up: How can a refinement report multiple failures? Add multiple issue objects to the context's issue collection during one callback.
QWhy is an issue path useful?
Use the context to attach an issue to a specific location in structured input. For example, a cross-field check can identify the field that should receive the error.
Follow-up: How would you associate an issue with a nested property? Set the issue path to the nested property's path segments.
QHow does the context relate to refine and superRefine?
Zod's regular refine API produces one custom issue, while the more flexible refinement callback can create issues with internal issue types. The context is the mechanism used to communicate those issues.
Follow-up: What should validation code do instead of throwing? Return normally and record a validation issue in the context.
Related
refinesuperRefinectx.issuesZodIssueabortwhen