Chapter 6: String Formats — ISO Dates, Network & Hashes

Core Idea

Zod's date/time, network, and hash format validators are regex-based (not full parsing libraries), which makes them fast and convenient for validating user input, but not a substitute for a real date/time library when you need calendar-aware logic.

Key Concepts

• z.iso.datetime(): strict ISO 8601 subset; no timezone offset by default. { offset: true } allows +02:00-style offsets; { local: true } allows timezone-less datetimes; { precision } pins the sub-second decimal digits (-1 = minute, 0 = seconds, 3 = milliseconds).
• z.iso.date(): strict YYYY-MM-DD only.
• z.iso.time(): HH:MM[:SS[.s+]], no Z or offset allowed; { precision } constrains decimal digits.
• z.ipv4() / z.ipv6(): IP address validation.
• z.cidrv4() / z.cidrv6(): CIDR block notation (192.168.0.0/24).
• z.mac(): 48-bit MAC address, colon-delimited by default ({ delimiter: "-" } to change).
• z.creditCard(): 12-19 digits with a valid Luhn checksum; accepts single spaces or hyphens as separators, not both mixed.
• z.hash(algorithm, { enc }): cryptographic hash validation (md5/sha1/sha256/sha384/sha512), hex encoding by default, or base64/base64url.
• z.stringFormat(name, validatorOrRegex): defines a custom named format; failures produce a descriptive "invalid_format" issue instead of a generic "custom" one.

Code Examples

const datetime = z.iso.datetime({ offset: true, precision: 3 });
datetime.parse("2020-01-01T06:15:00.123+02:00"); // ok

z.iso.date().parse("2020-01-01");  // ok
z.iso.date().parse("2020-1-1");    // throws (not zero-padded)

const card = z.creditCard();
card.parse("4111 1111 1111 1111"); // ok
card.parse("4111111111111112");    // throws (bad Luhn checksum)

const coolId = z.stringFormat("cool-id", (val) =>
  val.length === 100 && val.startsWith("cool-")
);

• What it demonstrates: precision/offset options for datetimes, and defining a fully custom string format.

Reference Tables

Hash algorithm	hex length	base64 length	base64url length
md5	32	24 (padded)	22
sha1	40	28 (padded)	27
sha256	64	44 (padded)	43
sha384	96	64	64
sha512	128	88 (padded)	86

Anti-patterns

• Treating z.iso.datetime() as a full date library: it's regex validation, not calendar math — it won't catch a logically invalid date it can't detect syntactically (relies on the ISO 8601 pattern, not real calendar validation beyond what the regex encodes).
• Expecting z.creditCard() to identify the card issuer: it only checks length + Luhn checksum, not issuer-specific prefixes.

Key Takeaways

1. ISO date/time validators are precision- and offset-configurable — read the options before reaching for a custom regex.
2. z.stringFormat() is the right tool for a recurring custom format: it produces a proper "invalid_format" issue instead of a generic "custom" one.
3. Network/identifier formats (MAC, CIDR, credit card) are strict about separator style — mixed or repeated separators are rejected.

Connects To

• String Formats — Identifiers & Web: email, UUID, URL, and phone validators.
• Codecs: for parsing an ISO string into an actual Date object rather than just validating its shape.