TypeScript type checking happens at compile time and is erased at runtime. A TypeScript type annotation on an API response is a promise to the compiler, not a guarantee at runtime. If the actual API response has a different structure than expected, TypeScript cannot catch it. Zod is a schema validation library that validates data at runtime and infers TypeScript types from the same schema.
What Zod Does
Zod lets you define a schema that describes what a piece of data should look like. At runtime, you call schema.parse(data) or schema.safeParse(data). Zod checks whether the data matches the schema. If it does, it returns the validated data with the correct TypeScript type inferred. If it does not, it returns detailed error messages describing exactly what was wrong.
This is especially valuable for API responses, form data, and any external input that you cannot guarantee will match your expectations.
A Basic Zod Schema
A Zod schema for a user object with a name, email, and optional age might look like: z.object({ name: z.string(), email: z.string().email(), age: z.number().optional() }). The call z.string().email() validates that the string is a valid email format, not just any string. Calling .optional() marks a field as not required.
Generating Zod Schemas from JSON
Writing Zod schemas for complex API responses by hand is tedious. A generator that infers the schema from a JSON sample produces a starting point that you then refine with additional constraints.
A string field in the JSON becomes z.string(). A number becomes z.number(). A boolean becomes z.boolean(). An array becomes z.array(). A nested object becomes a nested z.object(). Null values become z.null() or a union with z.nullable().
Refining Generated Schemas
After generation, add constraints that the sample alone cannot infer. An email field should have .email() added. A URL field should have .url(). A positive number should have .positive(). An enum-like string field should become z.enum(['value1', 'value2']). Required fields that might sometimes be absent should have .optional() added.
Using the DevHexLab JSON to Zod Tool
Open the tool at /tools/javascript/json-to-zod. Paste your JSON sample. Copy the generated Zod schema. Add it to your TypeScript project alongside the zod package import. Call safeParse on your API response to validate it at runtime.
Frequently Asked Questions
Should I use Zod for all external data?
Yes. Any data from outside your application (API responses, user input, file contents, message queue payloads) is untrusted. Validating it at the boundary with Zod prevents unexpected runtime errors deep in your application logic.
Is Zod just for TypeScript?
Zod is primarily a TypeScript library. It can be used in JavaScript without TypeScript, but the main benefit (inferred types from schemas) requires TypeScript.
Validate at the boundary and trust the data inside your application.