How to convert JSON to a Zod schema

Step 1 — Get a representative JSON sample

Copy a real response from the network tab, a webhook fixture, or your test data. The schema is only as accurate as the sample you start from, so prefer a payload that includes optional fields and arrays you care about.

{
  "id": 42,
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "isAdmin": false,
  "tags": ["math", "engine"]
}

Step 2 — Generate the schema

Paste the sample into the JSON → Zod converter. You'll get something like this:

import { z } from "zod";

export const User = z.object({
  "id": z.number().int(),
  "name": z.string(),
  "email": z.string().optional(),
  "isAdmin": z.boolean(),
  "tags": z.array(z.string()),
});

export type User = z.infer<typeof User>;

Note the last line: z.infer<typeof User> gives you a TypeScript type derived from the schema, so the type and the runtime validator can never drift apart.

Step 3 — Refine field constraints

The generator infers types but not business rules. Tighten the schema with Zod's built-in refinements:

import { z } from "zod";

export const User = z.object({
  id: z.number().int().positive(),
  name: z.string().min(1),
  email: z.string().email().optional(),
  isAdmin: z.boolean(),
  tags: z.array(z.string()).default([]),
});

export type User = z.infer<typeof User>;

• • .email() — validate email format
• • .min(1) / .max(100) — enforce string length bounds
• • .positive() / .int() — number constraints
• • .default([]) — provide a value when the field is missing
• • .refine(v => ..., "message") — custom rules

Step 4 — Add Zod validation at trust boundaries

The biggest win from a Zod schema is catching shape changes the moment they cross a boundary you do not fully control. Use .parse() when you expect valid data and want to fail loudly, or .safeParse() when you want to handle the failure inline.

import { User } from "./schemas";

export async function fetchUser(): Promise<User> {
  const res = await fetch("/api/me");
  const data = await res.json();
  return User.parse(data); // throws ZodError on shape mismatch
}

Step 5 — Reuse the schema in forms

The same schema can drive client-side form validation. With @hookform/resolvers/zod the integration is two lines:

import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { User } from "./schemas";

export function UserForm() {
  const { register, handleSubmit, formState: { errors } } = useForm({
    resolver: zodResolver(User),
  });
  return (
    <form onSubmit={handleSubmit((v) => console.log(v))}>
      <input {...register("name")} />
      {errors.name && <span>{errors.name.message}</span>}
    </form>
  );
}

Step 6 — Reuse in tRPC / API contracts

If you ship tRPC, pass the schema (or a transformed copy) directly as the procedure input. Same shape, same validator, same TypeScript types — end-to-end:

import { z } from "zod";
import { publicProcedure, router } from "./trpc";

export const userRouter = router({
  create: publicProcedure
    .input(User.omit({ id: true })) // reuse the schema, drop the server-generated id
    .mutation(async ({ input }) => {
      // input is fully typed and runtime-validated
      return db.user.create({ data: input });
    }),
});

Common pitfalls

• • Optionality is sample-dependent. A field is marked .optional() only if its value was null in the sample. Real APIs often have more optional fields than one sample reveals.
• • Integer vs number. Zod's .int() is added when every numeric value in the sample was an integer. APIs that occasionally return floats will fail validation — drop .int() if unsure.
• • Empty arrays lose element type. An empty array becomes z.array(z.unknown()). Provide a non-empty sample to get a useful element type.
• • Don't over-validate. Validating an internal value that's already typed is a code smell. Use Zod at trust boundaries: HTTP responses, form inputs, env vars, message queue payloads.

Troubleshooting generated Zod schemas

A generated schema is a strong first pass, but runtime validation gets strict quickly. These are the places developers most often need to edit the output before shipping it.

// Generated from a sample where email was null
email: z.string().nullable()

// Use this when the API may omit email entirely
email: z.string().email().optional()

// Use this when the API may send null or omit the field
email: z.string().email().nullable().optional()

const User = z.object({
  // Useful when a form field sends "42" as a string
  id: z.coerce.number().int().positive(),

  // Keep API timestamps as strings unless your app needs Date objects
  createdAt: z.string().datetime(),
});

FAQ