0Pricing
tRPC End-to-End Type Safe APIs · Lección

Definición de esquemas complejos de Zod

Aprenda a crear esquemas avanzados de Zod para objetos, arrays y reglas de validación personalizadas.

Definición de esquemas complejos de Zod es una lección gratuita de tRPC End-to-End Type Safe APIs en CoddyKit. Esta es la lección 2 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de tRPC End-to-End Type Safe APIs, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de tRPC End-to-End Type Safe APIs incluye 4 lecciones en total.

Partes de esta lección aún no han sido traducidas y se muestran en inglés.

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!

Preguntas frecuentes

¿La lección «Definición de esquemas complejos de Zod» es gratis?

Sí — el texto completo de «Definición de esquemas complejos de Zod» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de tRPC End-to-End Type Safe APIs, actualiza a CoddyKit PRO. El curso de tRPC End-to-End Type Safe APIs incluye 4 lecciones en total.

¿Qué aprenderé en «Definición de esquemas complejos de Zod»?

Aprenda a crear esquemas avanzados de Zod para objetos, arrays y reglas de validación personalizadas. Practicas tRPC End-to-End Type Safe APIs con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar tRPC End-to-End Type Safe APIs?

No se requiere experiencia previa. tRPC End-to-End Type Safe APIs en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 2 de 4.

¿Cuánto tiempo toma la lección «Definición de esquemas complejos de Zod»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de tRPC End-to-End Type Safe APIs?

Sí. Cada lección de tRPC End-to-End Type Safe APIs incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

  1. Introducción a los esquemas de Zod
  2. Definición de esquemas complejos de Zod
  3. Integración de Zod en procedimientos de tRPC
  4. Transformación y refinamiento de datos con Zod
← Volver a tRPC End-to-End Type Safe APIs