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
- Inspect
package.json, the selected lockfile/package manager/runtime,
TypeScript version, existing validator and import style, framework adapter,
trust boundary, and installed Zod version.
- 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.
- Decide missing versus
null, unknown keys, coercion, defaults,
transforms/codecs, numeric/date/byte representation, size/depth/cardinality
limits, and error exposure explicitly.
- 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
References
- Patterns and examples
- Zod 4.5 baseline
- Runnable common patterns
1---2name: zod-engineering3description: Select, add, migrate, review, test, or optimize Zod schemas; parse unknown JSON, form, query, environment, event, or tool data; map Zod errors; or use Zod-to-JSON-Schema and backend interoperability. Do not use for static TypeScript-only work, backend-native validation, public API design, authorization, sanitization, or domain-invariant ownership.4metadata:5 source: https://skillmd.com/skills/nledford/zod-engineering6---78# Zod Engineering910Use Zod as a runtime boundary adapter, not as a replacement for public-contract,11security, backend, or domain ownership.1213## Use When1415- A JavaScript or TypeScript boundary needs runtime parsing, normalization, or16 typed output.17- A repository selects or migrates Zod, including Zod 3-to-4 compatibility.18- A Zod schema, mapped validation error, generated JSON Schema, or performance19 claim needs review or tests.2021## Boundaries2223Parse `unknown` once at ingress; use parsed output afterwards; map it to plain24application or domain types. Independently validate outbound data that crosses25an untrusted or compatibility-sensitive boundary. Zod parsing is neither26authorization nor sanitization and does not own domain invariants.2728For a cross-language wire boundary use:2930`unknown JSON/IPC → Zod boundary schema → plain wire DTO → backend-native deserializer/validator → backend domain type`3132and reverse it through a stable serialized envelope before a UI/application33parse. See the [patterns and examples](references/patterns-and-examples.md#cross-language-interop).3435## Workflow36371. Inspect `package.json`, the selected lockfile/package manager/runtime,38 TypeScript version, existing validator and import style, framework adapter,39 trust boundary, and installed Zod version.402. Preserve a suitable established validator or Standard Schema adapter unless a41 migration is explicitly requested. Decide whether a public artifact, backend42 contract, or boundary schema owns the contract before writing a schema.433. Decide missing versus `null`, unknown keys, coercion, defaults,44 transforms/codecs, numeric/date/byte representation, size/depth/cardinality45 limits, and error exposure explicitly.464. Parse at the adapter, map inward, normalize errors at the adapter/render47 layer, and test the observable boundary.4849## Core Rules5051- Prefer schema-first contracts with `z.infer`, `z.input`, and `z.output`; use52 `z.toZod<T>()` only for type-first compatibility. Never maintain duplicate53 interfaces and schemas that can drift.54- Compose object shapes or use `.safeExtend()` rather than long `.extend()`55 chains. Use strict discriminated branches for overlapping event or intent56 unions.57- Use object getters for recursive objects; use `z.lazy()` when deferred58 non-object or mutually recursive shapes are clearer.59- Read [patterns and examples](references/patterns-and-examples.md) before60 selecting parse APIs, composition, error mapping, JSON Schema, or interop.6162## Errors And Security6364Map structured issue codes and bounded paths to a stable application/API error65envelope. Do not expose `ZodError`, default library wording, raw input,66transformed values, full issues, or `reportInput` without an explicit sanitized67policy. `z.treeifyError()` and `z.flattenError()` belong only in a presentation68adapter.6970Load [`security-review`](../security-review/SKILL.md) and71[`security-review-evidence`](../security-review-evidence/SKILL.md) for trust72boundaries; they own authorization, sanitization, resource limits, and safe73security evidence. Load [`internationalization-localization`](../internationalization-localization/SKILL.md)74for translated user messages.7576## Testing7778Test accepted and rejected boundaries; optional/null/unknown-key policy;79transforms and input/output divergence; sync and async parsing; mapped error80stability; and generated-contract parity. Add bounded property tests only when81the repository already uses a suitable generator. The runnable oracle is82[common patterns](examples/common-patterns.ts).8384Load [`test-driven-development`](../test-driven-development/SKILL.md) for an85implementation loop and [`testing-strategy`](../testing-strategy/SKILL.md) for86coverage review.8788## Performance And Migration8990Measure representative valid, invalid-with-diagnostics, boolean-validation,91schema construction/reuse, transform, depth, and async workloads before using92`z.compile()` or `z.validate()`. Upstream benchmarks are not local evidence.93Read the dated [Zod 4.5 baseline](references/zod-4.5-baseline.md) before a94version-sensitive change or migration.9596## Routing9798- [`javascript-typescript-engineering`](../javascript-typescript-engineering/SKILL.md)99 owns package/runtime/tooling mechanics.100- [`api-design`](../api-design/SKILL.md) owns public schemas, compatibility,101 versioning, and stable error envelopes.102- [`typescript-javascript-design-patterns`](../typescript-javascript-design-patterns/SKILL.md)103 owns adapter/core placement.104- [`performance-review`](../performance-review/SKILL.md) owns workload evidence.105- [`python-engineering`](../python-engineering/SKILL.md),106 [`rust-engineering`](../rust-engineering/SKILL.md), and107 [`csharp-dotnet-engineering`](../csharp-dotnet-engineering/SKILL.md) own108 backend-native DTO validation, mapping, serialization, and errors.109110## References111112- [Patterns and examples](references/patterns-and-examples.md)113- [Zod 4.5 baseline](references/zod-4.5-baseline.md)114- [Runnable common patterns](examples/common-patterns.ts)