What is validating-string-formats?

This Claude skill provides a comprehensive guide to the advanced features and performance optimizations introduced in Zod v4. It focuses on high-speed string validation, bidirectional data transformation using Codecs, and improved type safety, helping developers build more efficient and robust TypeScript applications while achieving up to 14x faster parsing speeds.

When should I use validating-string-formats?

validating-string-formats is useful in the following scenarios: • High-performance API validation: Implementing top-level functions like z.email(), z.uuid(), and z.url() to achieve significantly faster request parsing compared to legacy versions. • Data transformation and normalization: Using chained methods like .trim() and .toLowerCase() to clean user input automatically during the validation phase. • Handling web-based boolean inputs: Utilizing the stringbool type to seamlessly parse 'true', 'false', '1', and '0' from query parameters or form data into actual boolean values. • Complex serialization with Codecs: Creating bidirectional transformation logic to handle data conversion between storage formats (e.g., ISO strings) and application logic (e.g., Date objects). • Legacy codebase migration: Providing clear patterns and best practices for upgrading Zod v3 schemas to v4 to leverage modern performance benefits and cleaner syntax.

name	validating-string-formats
description	Guide to Zod v4 new features including top-level string formats, string transformations, codecs, and stringbool

Using Zod v4 Features

Purpose

Comprehensive guide to new features introduced in Zod v4 that improve developer experience, performance, and type safety.

Top-Level String Format Functions

Overview

Zod v4 moved string format validations to top-level functions for 14x faster parsing.

All optimized formats:

z.email() - Email validation
z.uuid() - UUID validation
z.iso.datetime() - ISO datetime
z.url() - URL validation
z.ipv4() / z.ipv6() - IP addresses
z.jwt() - JWT tokens
z.base64() - Base64 strings
z.hash('sha256') - Hash strings

Quick example:

const emailSchema = z.email().trim().toLowerCase();
const uuidSchema = z.uuid();
const datetimeSchema = z.iso.datetime();

With custom error:

const emailSchema = z.email({
  error: "Please enter a valid email address"
});

String Transformation Methods

Trim, Lower Case, Upper Case

z.string().trim()           // Remove whitespace
z.string().toLowerCase()    // Convert to lowercase
z.string().toUpperCase()    // Convert to uppercase

Chaining:

const emailSchema = z.email().trim().toLowerCase();

Execution order: Transformations execute left-to-right.

StringBool Type

Parse string representations of booleans:

const boolSchema = z.stringbool();

boolSchema.parse('true');   // true
boolSchema.parse('false');  // false
boolSchema.parse('1');      // true
boolSchema.parse('0');      // false

Use case: Query parameters and form data

const querySchema = z.object({
  active: z.stringbool(),
  verified: z.stringbool()
});

Codec Type

Bidirectional transformations for encode/decode:

const dateCodec = z.codec({
  decode: z.string().transform(s => new Date(s)),
  encode: z.date().transform(d => d.toISOString())
});

const decoded = dateCodec.parse('2024-01-01T00:00:00Z');
const encoded = dateCodec.encode(new Date());

Safe operations:

const result = dateCodec.safeDecode('invalid-date');
if (!result.success) {
  console.error(result.error);
}

Performance Optimizations

Bulk Array Validation (7x faster)

const arraySchema = z.array(itemSchema);
const items = arraySchema.parse([...]);

Passthrough for Performance

const schema = z.object({
  id: z.string()
}).passthrough();  // 10-20% faster, keeps extra fields

Best Practices

1. Use Top-Level Functions

z.email()           // ✅ 14x faster
z.string().email()  // ❌ Deprecated

2. Chain Transformations

z.email().trim().toLowerCase()  // ✅ Declarative

3. Leverage StringBool

z.stringbool()      // ✅ For "true"/"false" strings
z.boolean()         // ✅ For actual booleans

4. Brand IDs

z.string().brand<'UserId'>()
z.string().brand<'OrderId'>()

5. Codecs for Serialization

const dateCodec = z.codec({
  decode: z.iso.datetime().transform(s => new Date(s)),
  encode: z.date().transform(d => d.toISOString())
});

Migration from v3

String Formats:

z.email()          // ✅ v4
z.string().email() // ❌ v3

Error Customization:

z.string({ error: "Required" })  // ✅ v4
z.string({ message: "Required" }) // ❌ v3

Schema Composition:

schemaA.extend(schemaB.shape)  // ✅ v4
schemaA.merge(schemaB)         // ❌ v3

References

Validation: Use the validating-schema-basics skill from the zod-4 plugin
Migration: Use the migrating-v3-to-v4 skill from the zod-4 plugin
Transformations: Use the transforming-string-methods skill from the zod-4 plugin
Performance: Use the optimizing-performance skill from the zod-4 plugin

Success Criteria

✅ Using top-level format functions
✅ String transformations for user input
✅ StringBool for query params
✅ Codecs for date serialization
✅ Branded types for nominal typing
✅ Bulk array validation
✅ Discriminated unions for faster parsing

validating-string-formats

When & Why to Use This Skill

Use Cases