Skip to main content

​
Overview

Zod provides functions for validating UUIDs (Universally Unique Identifiers) according to RFC 9562/4122:
  • z.uuid() - Validates any UUID (versions 1-8)
  • z.uuidv4() - Validates UUID v4 specifically
  • z.uuidv6() - Validates UUID v6 specifically
  • z.uuidv7() - Validates UUID v7 specifically
import { z } from "zod";

const uuidSchema = z.uuid();
const uuidv4Schema = z.uuidv4();
const uuidv6Schema = z.uuidv6();
const uuidv7Schema = z.uuidv7();
Location in source: ~/workspace/source/packages/zod/src/v4/classic/schemas.ts:483-501

​
z.uuid()

Validates UUIDs of any version (1-8) with RFC-compliant variant bits.

​
Basic Usage

const schema = z.uuid();

schema.parse("9491d710-3185-4e06-bea0-6a2f275345e0"); // ✓ passes
schema.parse("invalid-uuid"); // ✗ throws

​
Valid UUID Examples

const schema = z.uuid();

// UUID v1
schema.parse("9491d710-3185-1e06-bea0-6a2f275345e0");

// UUID v2
schema.parse("9491d710-3185-2e06-bea0-6a2f275345e0");

// UUID v3
schema.parse("9491d710-3185-3e06-bea0-6a2f275345e0");

// UUID v4
schema.parse("9491d710-3185-4e06-bea0-6a2f275345e0");

// UUID v5
schema.parse("9491d710-3185-5e06-bea0-6a2f275345e0");
schema.parse("9491d710-3185-5e06-aea0-6a2f275345e0");
schema.parse("9491d710-3185-5e06-8ea0-6a2f275345e0");
schema.parse("9491d710-3185-5e06-9ea0-6a2f275345e0");

// Nil UUID
schema.parse("00000000-0000-0000-0000-000000000000");

// Max UUID
schema.parse("ffffffff-ffff-ffff-ffff-ffffffffffff");

​
Invalid UUID Examples

const schema = z.uuid();

// Invalid version (v0 doesn't exist)
schema.safeParse("9491d710-3185-0e06-bea0-6a2f275345e0").success; // false

// Invalid variant bits
schema.safeParse("9491d710-3185-5e06-0ea0-6a2f275345e0").success; // false

// Variant 0 (NCS backward compatibility - not standard)
schema.safeParse("b3ce60f8-e8b9-40f5-1150-172ede56ff74").success; // false

// Variant 2 (Microsoft backward compatibility - not standard)
schema.safeParse("92e76bf9-28b3-4730-cd7f-cb6bc51f8c09").success; // false

// Invalid format
schema.safeParse("invalid uuid").success; // false

// Extra character
schema.safeParse("9491d710-3185-4e06-bea0-6a2f275345e0X").success; // false

​
Custom Error Message

const schema = z.uuid("Please provide a valid UUID");

const result = schema.safeParse("invalid");
if (!result.success) {
  console.log(result.error.issues[0].message);
  // "Please provide a valid UUID"
}

​
z.uuidv4()

Validates UUID version 4 specifically (random UUIDs).

​
Basic Usage

const schema = z.uuidv4();

schema.parse("9491d710-3185-4e06-bea0-6a2f275345e0"); // ✓ passes (v4)
schema.parse("9491d710-3185-5e06-bea0-6a2f275345e0"); // ✗ throws (v5)

​
Example

const userIdSchema = z.object({
  id: z.uuidv4(),
  name: z.string(),
});

userIdSchema.parse({
  id: "550e8400-e29b-41d4-a716-446655440000",
  name: "John Doe"
}); // ✓ passes if id is v4

​
z.uuidv6()

Validates UUID version 6 (time-ordered UUIDs).

​
Basic Usage

const schema = z.uuidv6();

schema.parse("1e9c4470-3185-6000-8000-000000000000"); // ✓ passes (v6)
schema.parse("9491d710-3185-4e06-bea0-6a2f275345e0"); // ✗ throws (v4)
UUID v6 is designed to be time-ordered and sortable, making it useful for database primary keys and distributed systems.

​
z.uuidv7()

Validates UUID version 7 (Unix timestamp-based UUIDs).

​
Basic Usage

const schema = z.uuidv7();

schema.parse("017f22e2-79b0-7cc3-98c4-dc0c0c07398f"); // ✓ passes (v7)
schema.parse("9491d710-3185-4e06-bea0-6a2f275345e0"); // ✗ throws (v4)
UUID v7 embeds a Unix timestamp in the first 48 bits, making it both time-ordered and compatible with existing UUID infrastructure. It’s recommended for new applications requiring sortable identifiers.

​
Parameters

All UUID functions accept an optional parameter: 
z.uuid(params?: string | UUIDParams)
z.uuidv4(params?: string | UUIDv4Params)
z.uuidv6(params?: string | UUIDv6Params)
z.uuidv7(params?: string | UUIDv7Params)
  • string: Custom error message
  • Params object:
    • message?: string: Custom error message

​
Examples

​
Database ID Validation

const recordSchema = z.object({
  id: z.uuidv7(), // Modern sortable UUIDs
  created_at: z.date(),
  data: z.record(z.unknown()),
});

​
API Request Validation

const requestSchema = z.object({
  requestId: z.uuid(),
  userId: z.uuidv4(),
  sessionId: z.uuid().optional(),
});

​
Migration from Legacy IDs

const idSchema = z.union([
  z.uuidv4(), // Legacy IDs
  z.uuidv7(), // New IDs
]);

​
Version-Specific Validation

const schema = z.object({
  // Different UUID versions for different purposes
  transactionId: z.uuidv4(), // Random, unpredictable
  eventId: z.uuidv7(),       // Time-ordered, sortable
});

schema.parse({
  transactionId: "550e8400-e29b-41d4-a716-446655440000",
  eventId: "017f22e2-79b0-7cc3-98c4-dc0c0c07398f"
}); // ✓ passes

​
Return Type

All UUID schemas return a ZodUUID that validates and returns strings. 
type Output = string;
type Input = string;

​
Validation Rules

​
UUID Format

All UUID validators check for:
  1. Correct format: 8-4-4-4-12 hexadecimal digits
  2. Valid version bits in the 7th byte
  3. Valid variant bits in the 9th byte (RFC 9562/4122 compliant)

​
Version-Specific Rules

  • v4: Version bits = 0100 (4)
  • v6: Version bits = 0110 (6)
  • v7: Version bits = 0111 (7)

​
Variant Bits

All versions require RFC-compliant variant bits: 10xx in binary (8, 9, A, or B in hex).
The UUID validator strictly enforces RFC 9562/4122 standards. UUIDs with variant 0 (NCS) or variant 2 (Microsoft) are rejected by z.uuid() but may be accepted by the less strict z.guid().

Build docs developers (and LLMs) love

Get started for freeTalk to us