Zod Validation Mapping
Relevant source files
The following files were used as context for generating this wiki page:
Zod Validation Mapping is a specialized implementation pattern using the data-path library to bridge the gap between runtime validation errors and type-safe development. In typical TypeScript workflows, validation libraries like Zod return error locations as arrays of strings or numbers (e.g., ["user", "profile", "email"]). data-path enables developers to convert these dynamic runtime paths into path objects that can be compared against statically defined, type-safe lambda expressions.
This feature is primarily used to determine which specific UI field or state property corresponds to a validation issue. By using the unsafePath utility for dynamic error paths and the .equals() method for comparison, developers ensure that refactoring property names in the data structure automatically updates or breaks the validation mapping at compile-time, preventing "silent failures" common with string-based path logic.
Sources: README.md:310-315, skills/data-path/SKILL.md:53-58, skills/data-path/SKILL.md:99-105
Architecture and Workflow
The mapping architecture relies on the interoperability between Zod's ZodIssue structure and the data-path Relational Algebra. The workflow transforms raw validation data into a comparable format.
The Mapping Flow
- Schema Definition: A Zod schema is defined, and a corresponding TypeScript type is inferred.
- Target Path Definition: A type-safe target path is created using the
path<T>()constructor and a lambda expression. - Validation Execution: Data is parsed through
schema.safeParse(). - Path Conversion: For each issue found, the
issue.patharray is joined into a dot-notated string. - Dynamic Path Creation: This string is passed to
unsafePath<T>()to create adata-pathobject. - Relational Comparison: The dynamic path is compared to the target path using
.equals().
The diagram shows how runtime data from Zod is synchronized with static paths for field-specific error handling.
Sources: README.md:317-330, skills/data-path/SKILL.md:54-57
Key Components
unsafePath<T>(path: string)
This function is critical for validation mapping because Zod provides error paths as arrays that are only known at runtime. unsafePath allows the library to wrap these dynamic strings into the standard Path interface, enabling access to methods like .equals(), .startsWith(), and .includes().
Sources: src/tests/unsafe.spec.ts:13-18, skills/data-path/references/api.md:12
Relational Methods
The mapping logic primarily utilizes the relational algebra subset of the BasePath interface to reconcile different path origins.
| Method | Use Case in Validation |
|---|---|
.equals(other) | Exact match between a Zod error and a specific form field. |
.startsWith(other) | Check if an error occurred within a specific field group (e.g., "profile.*"). |
.includes(other) | Check if a specific field is affected by a higher-level validation error. |
Sources: src/impl/path-impl.ts:184-233, skills/data-path/references/api.md:46-51
Implementation Logic
The logic for determining a match is implemented in the PathImpl class. When comparing a Zod-generated path to a static path, the library performs a segment-by-segment comparison.
// Example of the comparison logic used in mapping
const agePath = path<FormData>(p => p.user.age);
// issue.path is ["user", "age"]
const errorPath = unsafePath<FormData>(issue.path.join("."));
if (errorPath.equals(agePath)) {
// Logic to display error on the 'Age' input
}
Sources: README.md:323-330, src/impl/path-impl.ts:203-205
Sequence of Validation Comparison
This sequence demonstrates the iterative process of checking runtime validation issues against pre-defined type-safe paths.
Sources: skills/data-path/SKILL.md:53-58, src/impl/path-impl.ts:203-205
Data Structures
The Zod mapping pattern relies on the Segment type, which allows for both string keys (object properties) and numeric indices (array elements). Zod's issue.path often contains numbers for array validation (e.g., ["users", 0, "email"]). unsafePath and the internal isCanonicalArrayIndex utility ensure these are parsed correctly to match the segments generated by the lambda expression.
Sources: src/types.ts:11, src/impl/path-impl.ts:103-110, src/tests/unsafe.spec.ts:28-31
Conclusion
Zod Validation Mapping transforms the traditionally fragile process of string-matching error paths into a robust, type-safe operation. By leveraging unsafePath to normalize Zod's runtime output and path.equals() for structural comparison, the system ensures that error handling remains synchronized with the underlying data model throughout the software lifecycle.