zod: one schema, the static type and the runtime guard

One schema, two outputs

How do you stop the type and the guard from ever drifting? The answer is to produce both from a single definition — you edit one thing and both update atomically. That single thing is a zod schema.

A zod schema is a runtime value (an object with a .parse method) that also carries enough type information for z.infer to extract a static type. You write the shape once:

import { z } from "zod";

const User = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
  profile: z.object({ bio: z.string() }).nullable(),
});

type User = z.infer<typeof User>;
// ^? { id: number; name: string; email: string; profile: { bio: string } | null }

The User type and the User schema are now derived from one definition. There is no second thing to keep in sync. Adding z.string() for a new field updates both the runtime check and the inferred type in one edit — drift is structurally impossible.

.parse throws; .safeParse returns a discriminated union

Two ways to run the check at the boundary:

const res = await fetch("/api/user/42");
const json: unknown = await res.json(); // type it unknown, not any

// .parse — throws a ZodError on failure
const user = User.parse(json); // ^? User  (or throws)

// .safeParse — returns a result you must narrow
const result = User.safeParse(json);
if (result.success) {
  result.data; // ^? User  — narrowed, validated
} else {
  result.error; // ^? ZodError  — paths + messages of every failure
}

.safeParse returns exactly the discriminated union you built by hand in lesson 1 — { success: true; data: User } | { success: false; error: ZodError } — except now the data branch is earned by a real runtime check, not asserted. Use .parse at trust boundaries you want to fail loud (a server route validating its own DB read), and .safeParse where a bad value is an expected outcome you render (form input, third-party webhook).

Note z.infer returns the output type. With transforms the input and output differ; we’ll see that below.

Composing: nesting, unions, discriminated unions

Schemas compose like the types they mirror. Build big shapes from small ones, and model the success/error wire contract as a discriminatedUnion:

const ApiResponse = z.discriminatedUnion("status", [
  z.object({ status: z.literal("ok"), data: User }),
  z.object({ status: z.literal("error"), code: z.number(), message: z.string() }),
]);

type ApiResponse = z.infer<typeof ApiResponse>;
// ^? { status: "ok"; data: User } | { status: "error"; code: number; message: string }

const parsed = ApiResponse.parse(json);
if (parsed.status === "ok") parsed.data; // ^? User

z.discriminatedUnion is faster and produces better errors than a plain z.union because it reads the discriminant first and only validates the matching member — the runtime mirror of the discriminated-union narrowing you learned in unit 02.

Transforms and refinements: where input and output diverge

A schema can do more than check — it can reshape and enforce business rules:

const DateFromString = z.string().transform((s) => new Date(s));
type In = z.input<typeof DateFromString>;  // ^? string
type Out = z.output<typeof DateFromString>; // ^? Date  (z.infer === output)

const Password = z
  .object({ pw: z.string().min(8), confirm: z.string() })
  .refine((o) => o.pw === o.confirm, { message: "passwords must match", path: ["confirm"] });

A transform means the value you parse in (a string) differs from the value you get out (a Date) — which is why z.infer is defined as the output type, and z.input exists for the pre-transform shape. A refine adds a predicate the static type can’t express (“these two fields are equal”) and attaches the failure to a field path for form display (this is exactly how you wire field-level errors in the Frontend track forms work).