Zod Schemas and Parsing

Implement validation at a named trust boundary using the project's installed Zod version. Selected boundary-validation, inference, and migration topics adapt secondsky's Zod skill, under the bundled LICENSE.secondsky-claude-skills. Examples here are rewritten and do not inherit its claim that every upstream example is verified.

Route precisely

• Use to create or change Zod schemas, parsing, coercion, transforms, refinements, codecs, or validation-error mapping for API payloads, forms, files, configuration, or external responses.
• Use code-review for a read-only diff review, vet-dependency to decide whether to adopt Zod, api-and-interface-design for an undecided public contract, and typescript-type-design for pure type-level mechanisms.
• Use deprecation-and-migration for a live contract rollout. A Zod upgrade can change accepted data, defaults, serialized output, and clients; a library upgrade alone does not authorize those changes.

Establish version and boundary

Read repository instructions, package/lock metadata, actual import path (zod, zod/v4, zod/mini, or core), compiler support, and local parsing/error conventions. Read installed declarations or version-matched official docs before using APIs. Do not infer a major version from the presence of z.codec: it arrived after the first Zod 4 release. Zod 4 documents TypeScript 5.5+ and strict checking; verify the supported combination instead of silently changing tsconfig.

Name the untrusted source, required input, normalized output, unknown-key policy, error consumer, and side-effect boundary. Validation is not authorization, output encoding, rate limiting, or proof that a database operation is safe. Preserve the project's manager, framework, and error contract; do not install a library or replace a validation system without task scope.

Implement the contract

1. Define small schemas and derive types from them. Distinguish z.input<typeof S> from z.output<typeof S> for coercion, defaults, transforms, and codecs; z.infer describes output. Consume the parsed data, not the original input narrowed by a success-only predicate.
2. Choose strip, reject, or preserve behavior for unknown keys deliberately. Defaults, optional, nullable, absent, and explicit undefined have different contracts. Check empty form strings and boolean/number coercion rather than assuming conversion validates the intended business meaning.
3. Choose .safeParse() for an explicit success/error branch, or .parse() when the caller deliberately handles ZodError or startup must fail. Existing correct exception handling is not a defect. Use async parsing for async refinements/transforms and await it.
4. Handle JSON syntax errors before schema parsing. safeParse does not catch an exception thrown while evaluating its argument, nor arbitrary exceptions from user transforms/refinements. Make expected callback failures validation issues using the installed API; keep unexpected infrastructure errors distinguishable.
5. Compose schemas without weakening constraints or accidentally overwriting fields. Check discriminated variants independently. For codecs, verify encode and decode separately, including invalid input and unsupported reverse transforms; use version-supported safe/async variants as needed. Do not promise that a generic transform is reversible.
6. Map errors to the existing API/UI contract. Preserve useful paths and codes without leaking raw input, secrets, or internal messages. Framework error adapters and form resolvers must match the installed versions.

Read references/parsing-contracts.md for executable examples and references/version-boundaries.md only for version or migration questions. Do not load unrelated framework integrations or require an ESLint plugin to use this workflow.

Verify and report

Run the configured type check separately from runtime validation tests. Include valid data, malformed JSON, invalid shape, unknown keys, coercion, defaults, transformed output versus original input, and async failure only where relevant. For codecs, include both directions and round-trip behavior under stated normalization. A schema's inferred type alone proves none of these runtime behaviors.

For a claimed fix, identify the old behavior rejected by the test and use a proportionate isolated negative control. Record exact package/compiler versions, selected cases, skips, and missing checks. Return changed schemas and consumers, input/output and error contracts, observed evidence, and rollout limits. Never claim all Zod 4 minor releases share every documented API.