Validating Schema Basics

const emailSchema = z.string().email();
const uuidSchema = z.string().uuid();
const datetimeSchema = z.string().datetime();
const urlSchema = z.string().url();

Correct v4 pattern:

const emailSchema = z.email();
const uuidSchema = z.uuid();
const datetimeSchema = z.iso.datetime();
const urlSchema = z.url();

Detection pattern:

grep -n "z\.string()\.email(" file.ts
grep -n "z\.string()\.uuid(" file.ts
grep -n "z\.string()\.datetime(" file.ts

2. Deprecated Error Customization

Anti-pattern:

z.string({ message: "Required" });
z.string({ invalid_type_error: "Must be string" });
z.string({ required_error: "Field required" });
z.object({}, { errorMap: customErrorMap });

Correct v4 pattern:

z.string({ error: "Required" });
z.string({ error: "Must be string" });
z.string({ error: "Field required" });
z.object({}, { error: customErrorMap });

Detection pattern:

grep -n "message:" file.ts | grep -v "error:"
grep -n "invalid_type_error:" file.ts
grep -n "required_error:" file.ts
grep -n "errorMap:" file.ts

3. Deprecated Merge Method

Anti-pattern:

const combined = schemaA.merge(schemaB);

Correct v4 pattern:

const combined = schemaA.extend(schemaB.shape);

Detection pattern:

grep -n "\.merge(" file.ts

4. Missing String Transformations

Anti-pattern:

const trimmed = input.trim();
const validated = z.string().parse(trimmed);

Correct v4 pattern:

const validated = z.string().trim().parse(input);

Detection pattern: Check for manual trim/toLowerCase/toUpperCase before validation.

Validation Process

Step 1: Scan for Deprecated APIs

Run pattern matching across TypeScript files:

find . -name "*.ts" -o -name "*.tsx" | while read file; do
  if grep -q "from ['\"]zod['\"]" "$file"; then
    echo "Checking: $file"

    grep -n "z\.string()\.email(" "$file" && echo "  ❌ Use z.email()"
    grep -n "z\.string()\.uuid(" "$file" && echo "  ❌ Use z.uuid()"
    grep -n "z\.string()\.datetime(" "$file" && echo "  ❌ Use z.iso.datetime()"
    grep -n "\.merge(" "$file" && echo "  ❌ Use .extend()"
    grep -n "message:" "$file" | grep -v "error:" && echo "  ❌ Use error parameter"
  fi
done

Step 2: Check Package Dependencies

Ensure Zod v4 installed:

grep "\"zod\"" package.json

Should show "zod": "^4.0.0" or higher.

Step 3: Review Type Inference

Verify type extraction uses correct syntax:

type User = z.infer<typeof userSchema>;
type UserInput = z.input<typeof userSchema>;
type UserOutput = z.output<typeof userSchema>;

Step 4: Validate Error Handling

Check safeParse pattern usage:

const result = schema.safeParse(data);
if (!result.success) {
  console.error(result.error.flatten());
  return;
}
const validData = result.data;

Common Migration Patterns

String Formats

Error Customization

Schema Composition

Remediation Steps

1. Update String Formats

Find and replace:

sed -i '' 's/z\.string()\.email()/z.email()/g' file.ts
sed -i '' 's/z\.string()\.uuid()/z.uuid()/g' file.ts
sed -i '' 's/z\.string()\.datetime()/z.iso.datetime()/g' file.ts

2. Update Error Parameters

Replace error customization:

sed -i '' 's/message:/error:/g' file.ts
sed -i '' 's/invalid_type_error:/error:/g' file.ts
sed -i '' 's/required_error:/error:/g' file.ts

3. Update Merge to Extend

sed -i '' 's/\.merge(/\.extend(/g' file.ts

4. Verify Changes

Run tests after migration:

npm test

Integration with Review Plugin

This skill can be invoked by the review plugin when reviewing Zod-related code:

/review zod-compatibility

The skill will check for all deprecated patterns and provide remediation guidance.

References

• Full migration guide: Use the migrating-v3-to-v4 skill from the zod-4 plugin
• String formats: Use the validating-string-formats skill from the zod-4 plugin
• Error handling: Use the customizing-errors skill from the zod-4 plugin

Cross-Plugin References:

• If validating external data sources, use the validating-external-data skill for understanding runtime validation requirements
• If applying schema validation patterns to database queries, use the ensuring-query-type-safety skill from prisma-6 for type-safe Prisma queries with proper input validation

Success Criteria

• ✅ Zero deprecated API usage in codebase
• ✅ All string formats use top-level functions
• ✅ Error customization uses unified error parameter
• ✅ Schema composition uses extend instead of merge
• ✅ Tests pass after migration
• ✅ TypeScript compilation succeeds without type errors