Zod · all subjects

schema definitions/string formats

20 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

String format types in Zod Core

zod/v4/core exports $ZodStringFormatTypes union including: $ZodGUID, $ZodUUID, $ZodEmail, $ZodURL, $ZodEmoji, $ZodNanoID, $ZodCUID, $ZodCUID2, $ZodULID, $ZodXID, $ZodKSUID, $ZodISODateTime, $ZodISODate, $ZodISOTime, $ZodISODuration, $ZodIPv4, $ZodIPv6, $ZodCIDRv4, $ZodCIDRv6, $ZodBase64, $ZodBase64URL, $ZodE164, and $ZodJWT. These are subclasses of $ZodString.

String format checks in Zod Core

zod/v4/core exports $ZodStringFormatChecks union including: $ZodCheckRegex, $ZodCheckLowerCase, $ZodCheckUpperCase, $ZodCheckIncludes, $ZodCheckStartsWith, $ZodCheckEndsWith, and the same format types as string format types ($ZodGUID, $ZodUUID, $ZodEmail, $ZodURL, $ZodEmoji, $ZodNanoID, $ZodCUID, $ZodCUID2, $ZodULID, $ZodXID, $ZodKSUID, $ZodISODateTime, $ZodISODate, $ZodISOTime, $ZodISODuration, $ZodIPv4, $ZodIPv6, $ZodCIDRv4, $ZodCIDRv6, $ZodBase64, $ZodBase64URL, $ZodE164, $ZodJWT).

String format types can act as both check and type

Some string format classes implement both $ZodCheck and $ZodType interfaces. They can be used as a type (z.email().parse(...)) or as a check (z.string().check(z.email()).parse(...)). When used, both ._zod.parse and ._zod.check are executed during parsing.

String format validators

Zod provides validators for common string formats: z.email(), z.uuid(), z.url(), z.httpUrl() (http or https only), z.hostname(), z.e164() (E.164 phone numbers), z.emoji() (single emoji), z.base64(), z.base64url(), z.hex(), z.jwt(), z.nanoid(), z.cuid(), z.cuid2(), z.ulid(), z.ipv4(), z.ipv6(), z.mac(), z.cidrv4() (ipv4 CIDR), z.cidrv6() (ipv6 CIDR), z.hash(algorithm) (supports 'sha1', 'sha256', 'sha384', 'sha512', 'md5'), z.iso.date(), z.iso.time(), z.iso.datetime(), z.iso.duration().

Custom email regex patterns in Zod

By default, z.email() uses a strict regex equivalent to: /^(?!\.)(?!.*\.\.([a-z0-9_'+\-\.]*)[a-z0-9_+-]@([a-z0-9][a-z0-9\-]*\.)+[a-z]{2,}$/i. Customize this with the pattern parameter: z.email({ pattern: /your regex/ }). Zod exports predefined regexes: z.regexes.email (default), z.regexes.html5Email (browser input validation), z.regexes.rfc5322Email (RFC 5322), z.regexes.unicodeEmail (loose regex for intl emails).

UUID validation with specific versions

z.uuid() validates any UUID. Specify a particular version with z.uuid({ version: 'v4' }). Supported versions: 'v1', 'v2', 'v3', 'v4', 'v5', 'v6', 'v7', 'v8'. Convenience methods: z.uuidv4(), z.uuidv6(), z.uuidv7(). Use z.guid() to validate any UUID-like identifier without enforcing RFC 9562/4122 requirements.

URL validation with hostname and protocol constraints

z.url() validates WHATWG-compatible URLs using the URL() constructor. Validate hostname with z.url({ hostname: /regex/ }). Validate protocol with z.url({ protocol: /regex/ }). To normalize URLs, use the normalize flag: z.url({ normalize: true }). Recommended schema for web URLs: z.url({ protocol: /^https?$/, hostname: z.regexes.domain }).

E.164 phone number validation

z.e164() validates phone numbers in E.164 format, which requires a leading +, a non-zero country code, and 7 to 15 digits total. Valid example: '+15555555555'. Invalid example: '555-555-5555'.

ISO 8601 datetime validation with options

z.iso.datetime() enforces ISO 8601 format. By default, no timezone offsets are allowed. Use z.iso.datetime({ offset: true }) to allow timezone offsets like +02:00 (but basic offsets like +02 are not allowed). Use z.iso.datetime({ local: true }) to allow unqualified datetimes without timezone. Use z.iso.datetime({ precision: n }) to constrain decimal precision: -1 for minute precision, 0 for seconds, positive numbers for fractional seconds (1 for deciseconds, 3 for milliseconds, etc.).

ISO date validation format

z.iso.date() validates strings in the format YYYY-MM-DD. Examples: '2020-01-01' passes, '2020-1-1' fails, '2020-01-32' fails.

ISO time validation with precision

z.iso.time() validates strings in format HH:MM[:SS[.s+]]. By default seconds and sub-second decimals are optional. No offsets or Z are allowed. Use z.iso.time({ precision: n }) to constrain precision: -1 for HH:MM, 0 for HH:MM:SS, 1 for deciseconds, 2 for centiseconds, 3 for milliseconds.

IP address validation

z.ipv4() validates IPv4 addresses like '192.168.0.0'. z.ipv6() validates IPv6 addresses like '2001:db8:85a3::8a2e:370:7334'.

CIDR block validation

z.cidrv4() validates IPv4 CIDR notation like '192.168.0.0/24'. z.cidrv6() validates IPv6 CIDR notation like '2001:db8::/32'.

MAC address validation

z.mac() validates standard 48-bit IEEE 802 MAC addresses. By default expects colon-delimited format like '00:1A:2B:3C:4D:5E'. Custom delimiter with z.mac({ delimiter: '-' }) for dash-delimited format. Must be standard format (consecutive pairs) and case must be consistent.

JWT validation

z.jwt() validates JSON Web Tokens. Can specify algorithm with z.jwt({ alg: 'HS256' }).

Cryptographic hash validation

z.hash(algorithm) validates cryptographic hash values. Supported algorithms: 'md5', 'sha1', 'sha256', 'sha384', 'sha512'. By default expects hexadecimal encoding. Specify encoding with z.hash('sha256', { enc: 'hex' }) for hex (default), { enc: 'base64' } for base64, or { enc: 'base64url' } for base64url without padding.

Hash length and padding expectations

Expected lengths for hash values: md5 is 32 chars hex / 24 chars base64 (22+==) / 22 chars base64url. sha1 is 40 hex / 28 base64 (27+=) / 27 base64url. sha256 is 64 hex / 44 base64 (43+=) / 43 base64url. sha384 is 96 hex / 64 base64 (no padding) / 64 base64url. sha512 is 128 hex / 88 base64 (86+==) / 86 base64url.

Custom string format validation

Use z.stringFormat(name, validation) to define custom string formats. The validation parameter can be a function (val) => boolean or a regex. This produces 'invalid_format' issues instead of generic 'custom' errors. Example: z.stringFormat('cool-id', (val) => val.length === 100 && val.startsWith('cool-')) or z.stringFormat('cool-id', /^cool-[a-z0-9]{95}$/).

Top-level string format functions

String formats have been promoted to top-level functions: z.email(), z.uuidv4(), z.uuidv6(), z.uuidv7(), z.ipv4(), z.ipv6(), z.cidrv4(), z.cidrv6(), z.url(), z.e164(), z.base64(), z.base64url(), z.jwt(), z.lowercase(), z.iso.date(), z.iso.datetime(), z.iso.duration(), z.iso.time(). Method equivalents are deprecated.

z.email() supports custom regex patterns

z.email() accepts a custom regex via the pattern option. Zod exports common patterns: z.regexes.email (default Gmail rules), z.regexes.html5Email (browser validation), z.regexes.rfc5322Email (RFC 5322), z.regexes.unicodeEmail (loose, Unicode-friendly).

Give your agent this brain