Zod

1. Establish the version and boundary

Read the consuming package's resolved Zod version, imports, TypeScript settings, existing schemas, adapters, and nearest tests. Account for multiple installed versions. Match the project's import style and preserve its validation layer. Use strict TypeScript checking; investigate incompatible adapters before changing their schema types. This skill targets Zod 4 Classic, with 4.6.5 as its documentation baseline; not every 4.x API is interchangeable.

Identify the raw representation, accepted values, parsed output, failure consumer, and synchronous or asynchronous execution. Finish with those five decisions explicit for each changed boundary.

2. Encode the contract

Reuse existing domain schemas where their accepted values and unknown-key policy match. Infer application-owned types from schemas; for externally owned contracts, check compatibility without erasing the concrete schema's inferred type.

Derive create, update, and public-response schemas deliberately. .partial() is shallow; a PATCH contract must define absent versus explicit null and which fields are writable. A database row schema is not automatically a safe write or response schema. Select allowed fields before persistence or serialization.

Compose plain object shapes with .extend() or explicit shape spread. Check overwritten keys and choose the resulting unknown-key policy. For refined objects on 4.1+, use .safeExtend(): spreading .shape preserves fields, not object-level checks. Its assignability check does not prove preservation of every runtime restriction. Prefer object composition over an intersection when downstream code needs object methods.

Finish when requiredness, variants, extra keys, and input/output differences are intentional rather than side effects of schema composition.

3. Parse and consume the result

Treat external data as unknown until the boundary succeeds. Choose safeParse for an expected validation-failure branch, or parse where throwing a ZodError matches the existing caller. Consume parsed data, including normalization, transforms, defaults, and stripped keys; a successful check does not rewrite input.

import * as z from "zod";

const RenameProject = z.strictObject({
  name: z.string().trim().min(1).max(120),
});

type RenameProjectInput = z.input<typeof RenameProject>;
type RenameProjectData = z.output<typeof RenameProject>;

export function validateRename(input: unknown) {
  const result = RenameProject.safeParse(input);
  if (!result.success) {
    return { ok: false as const, issues: result.error.issues };
  }
  return { ok: true as const, data: result.data };
}

Any asynchronous refinement or transform requires awaited parseAsync or safeParseAsync throughout its callers. Safe parsing handles validation failures, not arbitrary exceptions from user callbacks or unavailable services. Keep those failures distinct from invalid input.

For Zod 4.6+, .validate() answers only whether input is acceptable. Use it only when neither parsed output nor issues are needed; it narrows the input type, not the output type. See interop.md for measured hot paths.

Validate at the server trust boundary even when the client uses the same schema. Keep authorization, database uniqueness, and transaction guarantees in their existing enforcement layers. Format validation is not authentication, sanitization, or permission to fetch a URL. Bound request size and nesting before costly parsing.

Finish when downstream effects receive the parsed contract and each failure has an explicit owner.

4. Verify the changed boundary

Run the project's existing typecheck and focused tests. Select relevant cases:

• Valid input yields the exact expected output, not merely success: true.
• Wrong types, absent keys, explicit undefined, null, empty and whitespace-only strings take the intended paths.
• Extra keys and privileged fields cannot cross the write or response boundary.
• Union overlap, nested paths, numeric limits, and enum-record omissions behave as specified.
• Coercion, defaults, transform order, and async rejection preserve the contract.
• Composition retains cross-field checks; adapters receive the right input/output types and error shape.
• Version changes preserve recorded fixtures or document intentional differences.

Report the resolved version, changed contracts, executed checks, and any untested integration.