0Pricing
tRPC End-to-End Type Safe APIs · Lesson

Defining Complex Zod Schemas

Learn to create advanced Zod schemas for objects, arrays, and custom validation rules.

Defining Complex Zod Schemas is a free tRPC End-to-End Type Safe APIs lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the tRPC End-to-End Type Safe APIs learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Beyond Basic Zod Types

Welcome back! In the previous lesson, we learned about Zod's basic types like string, number, and boolean. These are great for simple validations.

But real-world data is rarely simple! We often deal with complex structures like user profiles, product lists, or nested configurations.

Today, we'll dive into defining schemas for these more intricate data types, making your tRPC APIs even more robust.

Crafting Object Schemas

The z.object() method is your go-to for validating JavaScript objects. You define each property's schema within it.

  • Each key in the object corresponds to a property in your data.
  • The value for each key is another Zod schema, defining that property's type and rules.
  • By default, all properties defined in z.object() are required.

Let's see how to define a schema for a simple user object:

import { z } from 'zod';

const UserProfileSchema = z.object({
  username: z.string().min(3),
  email: z.string().email(),
  age: z.number().int().positive()
});

Running an Object Schema

To validate data against an object schema, you use the .parse() method. If the data doesn't match, it throws a ZodError.

Try running this example to see valid and invalid object data in action!

import { z } from 'zod';

const UserProfileSchema = z.object({
  username: z.string().min(3, "Username must be at least 3 chars"),
  email: z.string().email("Invalid email format"),
  age: z.number().int().positive("Age must be a positive integer")
});

function validateUser(userData: unknown) {
  try {
    const parsedUser = UserProfileSchema.parse(userData);
    console.log("Validation Success:", JSON.stringify(parsedUser));
  } catch (error: any) {
    console.log("Validation Error:", error.issues[0].message);
  }
}

console.log("--- Valid User ---");
validateUser({
  username: "coderKid",
  email: "kid@example.com",
  age: 12
});

console.log("\n--- Invalid User (Age) ---");
validateUser({
  username: "coderKid",
  email: "kid@example.com",
  age: -5
});

Nesting Objects for Complexity

Applications often have data that's structured in a hierarchical way. Zod handles this beautifully by allowing you to nest object schemas.

You can define an object schema, and then use it as the type for a property within another object schema. This keeps your schemas organized and reusable.

Here's how you might define a ShippingAddress schema and nest it within a OrderSchema:

import { z } from 'zod';

const ShippingAddressSchema = z.object({
  street: z.string().min(5),
  city: z.string().min(2),
  zipCode: z.string().regex(/^\d{5}(-\d{4})?$/)
});

const OrderSchema = z.object({
  orderId: z.string().uuid(),
  items: z.array(z.string()), // Array of item IDs
  address: ShippingAddressSchema // Nested object!
});

Working with Array Schemas

When you need to validate a list of items, z.array() comes to the rescue. It takes another Zod schema as its argument, defining the type of each element in the array.

You can validate arrays of basic types (like strings or numbers) or even arrays of complex objects.

  • z.array(z.string()): An array where every element must be a string.
  • z.array(z.object({...})): An array where every element must conform to a specific object schema.
import { z } from 'zod';

const TagSchema = z.string().min(2).max(20);
const TagsArraySchema = z.array(TagSchema).min(1).max(5);

const ProductSchema = z.object({
  id: z.string().uuid(),
  name: z.string().min(3),
  price: z.number().positive(),
  tags: TagsArraySchema // Array of strings (tags)
});

Runnable Array Schema Example

Let's put z.array() to the test. This example defines a schema for an array of numbers and then tries to validate both a valid and an invalid array.

Notice how you can chain methods like .min() and .max() directly onto the array schema itself to enforce array length constraints.

import { z } from 'zod';

const NumberListSchema = z.array(z.number()).min(2, "Must have at least 2 numbers").max(5, "Cannot have more than 5 numbers");

function validateNumberList(listData: unknown) {
  try {
    const parsedList = NumberListSchema.parse(listData);
    console.log("Validation Success:", JSON.stringify(parsedList));
  } catch (error: any) {
    console.log("Validation Error:", error.issues[0].message);
  }
}

console.log("--- Valid List ---");
validateNumberList([10, 20, 30]);

console.log("\n--- Invalid List (Too Short) ---");
validateNumberList([5]);

console.log("\n--- Invalid List (Wrong Type) ---");
validateNumberList([1, "two", 3]);

Unions and Enums for Choices

Sometimes, a property can have one of several possible types or values. Zod provides z.union() and z.enum() for these scenarios.

  • z.union([schema1, schema2]): Allows a value to match any one of the provided schemas. E.g., a status could be a string or a number.
  • z.enum(['val1', 'val2']): Restricts a string value to be one of a predefined set of literal strings. This is perfect for fixed categories or states.
import { z } from 'zod';

const IDSchema = z.union([z.string().uuid(), z.number().int().positive()]);

const StatusEnum = z.enum(['pending', 'processing', 'completed', 'failed']);

const TaskSchema = z.object({
  taskId: IDSchema, // Could be UUID string or positive integer
  description: z.string(),
  status: StatusEnum // Must be one of 'pending', 'processing', etc.
});

Custom Validation with .refine()

Zod's built-in validators cover many cases, but what if you have a unique rule? The .refine() method lets you add custom validation logic to any schema.

It takes two arguments:

  • A predicate function that returns true for valid data, false otherwise.
  • An error message string or an object with a custom message.

.refine() runs after all other schema validations, so you can be sure the data has the correct basic type and structure first.

import { z } from 'zod';

const PasswordSchema = z.string()
  .min(8, "Password must be at least 8 characters long")
  .refine(password => /[A-Z]/.test(password), "Password must contain at least one uppercase letter")
  .refine(password => /[0-9]/.test(password), "Password must contain at least one number");

const UserLoginSchema = z.object({
  email: z.string().email(),
  password: PasswordSchema
});

Running Custom Refine Example

Let's test a schema with a custom .refine() rule. We'll ensure a given date string is in the future.

This shows how powerful .refine() can be for enforcing business logic that isn't covered by standard type checks.

import { z } from 'zod';

const FutureDateSchema = z.string().datetime()
  .refine(
    (dateString) => new Date(dateString) > new Date(),
    "Date must be in the future"
  );

function validateFutureDate(dateInput: unknown) {
  try {
    const parsedDate = FutureDateSchema.parse(dateInput);
    console.log("Validation Success:", parsedDate);
  } catch (error: any) {
    console.log("Validation Error:", error.issues[0].message);
  }
}

console.log("--- Valid Future Date ---");
const future = new Date();
future.setDate(future.getDate() + 1);
validateFutureDate(future.toISOString());

console.log("\n--- Invalid Past Date ---");
const past = new Date();
past.setDate(past.getDate() - 1);
validateFutureDate(past.toISOString());

Optional Properties & Defaults

Not every property in an object is always required. Zod helps you mark properties as optional and even provide default values.

  • .optional(): Makes a property optional. If it's missing, Zod won't throw an error.
  • .nullable(): Allows a property to be null.
  • .default(value): Provides a fallback value if the property is missing or undefined.

Using these can make your schemas more flexible and handle partial data gracefully.

import { z } from 'zod';

const UserSettingsSchema = z.object({
  theme: z.enum(['light', 'dark']).default('light'), // Default to 'light'
  notifications: z.boolean().optional(), // Optional boolean
  bio: z.string().max(200).nullable().optional() // Optional, can be null
});

Quick Check on Zod Schemas

You've learned how to define object and array schemas, use unions/enums, and even add custom validation. Which of the following statements about Zod's complex schemas is TRUE?

Recap: Mastering Complex Schemas

Great job! You've taken a significant leap in your ability to define robust data validations with Zod.

We covered:

  • z.object() for structured data, including nesting.
  • z.array() for lists of items.
  • z.union() and z.enum() for handling multiple possible types or predefined values.
  • .refine() for powerful custom validation rules.
  • Making properties optional, nullable, and setting defaults.

These tools are essential for building secure and predictable tRPC APIs. Next, we'll integrate these Zod schemas directly into your tRPC procedures!

Frequently asked questions

Is the “Defining Complex Zod Schemas” lesson free?

Yes — the full text of “Defining Complex Zod Schemas” is free to read here on the web, and the tRPC End-to-End Type Safe APIs course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the tRPC End-to-End Type Safe APIs course, upgrade to CoddyKit PRO.

What will I learn in “Defining Complex Zod Schemas”?

Learn to create advanced Zod schemas for objects, arrays, and custom validation rules. You practise tRPC End-to-End Type Safe APIs with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start tRPC End-to-End Type Safe APIs?

No prior experience is required. tRPC End-to-End Type Safe APIs on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Defining Complex Zod Schemas” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this tRPC End-to-End Type Safe APIs lesson?

Yes. Every tRPC End-to-End Type Safe APIs lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Introduction to Zod Schemas
  2. Defining Complex Zod Schemas
  3. Integrating Zod in tRPC Procedures
  4. Transforming and Refining Zod Data
← Back to tRPC End-to-End Type Safe APIs