Validate UUID identifiers
Validate request, route, or database identifiers that must be standards-compliant UUIDs.
Zod · Module
.uuid
z.uuid() creates a Zod schema for validating RFC 9562/4122-compliant UUID strings. It can restrict validation to a specified UUID version, while z.guid() handles less strict UUID-like identifiers.
How it works
z.uuid() constructs a string schema that accepts UUIDs conforming to the RFC 9562/4122 format. Pass a version option to restrict accepted UUID versions; use the dedicated z.uuidv4(), z.uuidv6(), or z.uuidv7() helpers for common cases, while z.guid() accepts UUID-like hexadecimal identifiers without the UUID variant constraint.
Syntax
z.uuid(options?)Parameters
| Name | Type | Description |
|---|---|---|
options | object | Optional configuration object; its version property restricts validation to a supported UUID version. |
Returns
A Zod schema that validates UUID strings.
Key points
- Call
z.uuid()to create a schema that validates UUID strings. - The version option supports UUID versions v1 through v8.
- Use
{ version: "v4" }when the schema should accept only version 4 UUIDs.
Common mistakes
- The validator enforces the UUID variant bits required by RFC 9562/4122; UUID-like strings that only match the hexadecimal shape may need
z.guid()instead. - Do not use
z.uuid()when compatibility with non-standard UUID-like identifiers is required; choose the more permissive validator.
Example: Validate a version 4 UUID
import { z } from "zod";
const UserId = z.uuid({ version: "v4" });
const result = UserId.safeParse("550e8400-e29b-41d4-a716-446655440000");
if (result.success) {
console.log(result.data);
}Creates a schema for RFC-compliant version 4 UUIDs and validates a value without throwing.
When to use it
Enforce a UUID version
Accept only identifiers from a required UUID generation version.
Accept UUID-like values
Handle external systems that emit UUID-shaped values without valid RFC variant bits.
Interview questions
QWhat does z.uuid() validate?
z.uuid() returns a Zod schema for validating UUID strings. It checks the RFC 9562/4122 UUID requirements rather than merely checking the general hexadecimal layout.
Follow-up: How would you validate only version 4 UUIDs? Use z.uuid({ version: "v4" }), or the convenience schema z.uuidv4().
QHow can validation be restricted to a UUID version?
Pass an options object with a version property, such as { version: "v4" }. The documented supported versions are v1 through v8.
Follow-up: What if the input is UUID-shaped but does not satisfy the RFC variant requirement? Use z.guid(), which is intended for UUID-like identifiers.
QWhen should z.guid() be used instead of z.uuid()?
z.guid() is the permissive alternative for UUID-like identifiers. Unlike z.uuid(), it does not enforce the RFC-required variant bits.
Follow-up: Which convenience helpers are documented for specific versions? z.uuidv4(), z.uuidv6(), and z.uuidv7().
Related
z.guid()z.uuidv4()z.uuidv6()z.uuidv7()