Zod Engineering

Zod Engineering

Use Zod as a runtime boundary adapter, not as a replacement for public-contract, security, backend, or domain ownership.

Use When

• A JavaScript or TypeScript boundary needs runtime parsing, normalization, or typed output.
• A repository selects or migrates Zod, including Zod 3-to-4 compatibility.
• A Zod schema, mapped validation error, generated JSON Schema, or performance claim needs review or tests.

Boundaries

Parse unknown once at ingress; use parsed output afterwards; map it to plain application or domain types. Independently validate outbound data that crosses an untrusted or compatibility-sensitive boundary. Zod parsing is neither authorization nor sanitization and does not own domain invariants.

For a cross-language wire boundary use:

unknown JSON/IPC → Zod boundary schema → plain wire DTO → backend-native deserializer/validator → backend domain type

and reverse it through a stable serialized envelope before a UI/application parse. See the patterns and examples.

Workflow

1. Inspect package.json, the selected lockfile/package manager/runtime, TypeScript version, existing validator and import style, framework adapter, trust boundary, and installed Zod version.
2. Preserve a suitable established validator or Standard Schema adapter unless a migration is explicitly requested. Decide whether a public artifact, backend contract, or boundary schema owns the contract before writing a schema.
3. Decide missing versus null, unknown keys, coercion, defaults, transforms/codecs, numeric/date/byte representation, size/depth/cardinality limits, and error exposure explicitly.
4. Parse at the adapter, map inward, normalize errors at the adapter/render layer, and test the observable boundary.

Core Rules

• Prefer schema-first contracts with z.infer, z.input, and z.output; use z.toZod<T>() only for type-first compatibility. Never maintain duplicate interfaces and schemas that can drift.
• Compose object shapes or use .safeExtend() rather than long .extend() chains. Use strict discriminated branches for overlapping event or intent unions.
• Use object getters for recursive objects; use z.lazy() when deferred non-object or mutually recursive shapes are clearer.
• Read patterns and examples before selecting parse APIs, composition, error mapping, JSON Schema, or interop.

Errors And Security

Map structured issue codes and bounded paths to a stable application/API error envelope. Do not expose ZodError, default library wording, raw input, transformed values, full issues, or reportInput without an explicit sanitized policy. z.treeifyError() and z.flattenError() belong only in a presentation adapter.

Load security-review and security-review-evidence for trust boundaries; they own authorization, sanitization, resource limits, and safe security evidence. Load internationalization-localization for translated user messages.

Testing

Test accepted and rejected boundaries; optional/null/unknown-key policy; transforms and input/output divergence; sync and async parsing; mapped error stability; and generated-contract parity. Add bounded property tests only when the repository already uses a suitable generator. The runnable oracle is common patterns.

Load test-driven-development for an implementation loop and testing-strategy for coverage review.

Performance And Migration

Measure representative valid, invalid-with-diagnostics, boolean-validation, schema construction/reuse, transform, depth, and async workloads before using z.compile() or z.validate(). Upstream benchmarks are not local evidence. Read the dated Zod 4.5 baseline before a version-sensitive change or migration.

Routing

• javascript-typescript-engineering owns package/runtime/tooling mechanics.
• api-design owns public schemas, compatibility, versioning, and stable error envelopes.
• typescript-javascript-design-patterns owns adapter/core placement.
• performance-review owns workload evidence.
• php-engineering, python-engineering, rust-engineering, and csharp-dotnet-engineering own backend-native DTO validation, mapping, serialization, and errors.

References

• Patterns and examples
• Zod 4.5 baseline
• Runnable common patterns