uuid(), guid()

Creates validators that accept UUID and GUID strings.

Signature

function uuid(): UuidValidator
function guid(): UuidValidator

Accepted Values

uuid()

Accepts RFC 9562 UUIDs. Case-insensitive, requires hyphens. Optionally validates the version digit.

Input	Result
"550e8400-e29b-41d4-a716-446655440000"	✅ UUID v4
"550E8400-E29B-41D4-A716-446655440000"	✅ Case-insensitive
"00000000-0000-0000-0000-000000000000"	✅ Nil UUID
"018e0e00-9e4b-7b3c-9a1e-123456789abc"	✅ UUID v7
"550e8400e29b41d4a716446655440000"	❌ No hyphens
"not-a-uuid"	❌ Not a UUID

Version-Specific UUID

// Restrict to a specific UUID version
uuid({ version: "4" })   // Only UUIDv4
uuid({ version: "7" })   // Only UUIDv7
uuid({ version: "any" }) // Any version (default)

Input	uuid({ version: "4" })	uuid({ version: "7" })
"550e8400-e29b-41d4-a716-446655440000"	✅ v4	❌ not v7
"018e0e00-9e4b-7b3c-9a1e-123456789abc"	❌ not v4	✅ v7

Supported versions: "1", "2", "3", "4", "5", "6", "7", "8".

guid()

Permissive GUID format. Case-insensitive, no variant/version bit validation. Does not accept braces.

Input	Result
"550e8400-e29b-41d4-a716-446655440000"	✅
"{550e8400-e29b-41d4-a716-446655440000}"	❌ Braces not accepted
"550E8400-E29B-41D4-A716-446655440000"	✅ Uppercase accepted
"550e8400e29b41d4a716446655440000"	❌ No hyphens

Refinements

UUID validators have no type-specific refinements. They support only the chainable methods (.optional(), .default(), .describe(), .secret(), .validate()).

Examples

const env = defineEnv({
  SESSION_ID: uuid(),
  CORRELATION_ID: uuid().optional(),
  UUIDV7_ONLY: uuid({ version: "7" }),
  LEGACY_GUID: guid().describe("Legacy GUID format identifier"),
})