1. Primitive, Coercion & String Format Constructors

This module catalogs Zod v4.6.7's scalar primitive constructors (z.string, z.number, z.int, z.bigint, z.boolean, z.date), literal and enumeration types (z.literal, z.enum, z.templateLiteral), input coercion (z.coerce), bidirectional z.stringbool, top-level string format constructors (z.email, z.uuid, z.url, z.jwt, z.ipv4, z.ipv6, z.hash), and ISO 8601 temporal schemas (z.iso.*).

from drawlib import canvas
from drawlib.diagrams.architecture import ArchitectureDiagram, Node, NodeGroup, PhosphorIcon
from drawlib.lines import line
from drawlib.styles import Styles
from drawlib.text import text

canvas.clear()
canvas.setup(width=184, height=106, dpi=150)

text(
    (92, 100.5),
    "$ZodType / ZodType Primitive, Coercion & String Format Hierarchy",
    style=Styles.DarkBold.patch(text_size=13.0),
)

d = ArchitectureDiagram(
    node_style=Styles.PrimaryBold,
    node_text_style=Styles.DarkBold.patch(text_size=10.0),
    edge_style=Styles.PrimaryBold,
    edge_text_style=Styles.DarkBold.patch(text_size=10.0),
    node_card_style=Styles.Neutral,
)

# Root Base Class
root = d.add(
    Node(
        "ZodType<Output, Input>  (extends core.$ZodType)\nparse / safeParse / check / refine / toJSONSchema",
        width=92,
        height=12.5,
        icon=PhosphorIcon.TREE_STRUCTURE,
        icon_size=5.8,
        style=Styles.WhiteBold,
        text_style=Styles.WhiteBold.patch(text_size=10.5),
        card_style=Styles.PrimaryFlat,
    ),
    xy=(88.0, 84.0),
)

# Group 1: Scalar Primitives
g_prim = d.add(
    NodeGroup(title="Scalar Primitives", padding=4.5),
    xy=(2.0, 4.0),
)
g_prim.add(
    Node("ZodString\nz.string()", width=36, height=12.5, icon=PhosphorIcon.TEXT_T, icon_size=5.5, card_style=Styles.PrimaryNeutral),
    xy=(22.5, 49.0),
)
g_prim.add(
    Node("ZodNumber / ZodInt\nz.number() / z.int()", width=36, height=12.5, icon=PhosphorIcon.HASH, icon_size=5.5, card_style=Styles.Neutral),
    xy=(22.5, 34.0),
)
g_prim.add(
    Node("ZodBigInt / Int64\nz.bigint() / z.int64()", width=36, height=12.5, icon=PhosphorIcon.CALCULATOR, icon_size=5.5, card_style=Styles.Neutral),
    xy=(22.5, 19.0),
)
g_prim.add(
    Node("ZodBoolean / ZodDate\nz.boolean() / z.date()", width=36, height=12.5, icon=PhosphorIcon.CALENDAR, icon_size=5.5, card_style=Styles.Neutral),
    xy=(22.5, 4.0),
)

# Group 2: Literals, Enums & Coercion
g_enum = d.add(
    NodeGroup(title="Literals, Enums & Coercion", padding=4.5),
    xy=(50.0, 4.0),
)
g_enum.add(
    Node("ZodLiteral<T>\nz.literal(val | vals[])", width=40, height=12.5, icon=PhosphorIcon.TAG, icon_size=5.5, card_style=Styles.Neutral),
    xy=(24.5, 49.0),
)
g_enum.add(
    Node("ZodEnum<T>\nz.enum([...]) / extract", width=40, height=12.5, icon=PhosphorIcon.LIST_BULLETS, icon_size=5.5, card_style=Styles.PrimaryNeutral),
    xy=(24.5, 34.0),
)
g_enum.add(
    Node("ZodTemplateLiteral\nz.templateLiteral([...])", width=40, height=12.5, icon=PhosphorIcon.CODE, icon_size=5.5, card_style=Styles.Neutral),
    xy=(24.5, 19.0),
)
g_enum.add(
    Node("z.coerce.*  &  z.stringbool()\nInput Coercion & Bool Codec", width=40, height=12.5, icon=PhosphorIcon.ARROWS_CLOCKWISE, icon_size=5.5, card_style=Styles.SecondaryNeutral),
    xy=(24.5, 4.0),
)

# Group 3: ZodStringFormat Subclasses (v4 Top-Level Formats)
g_fmt = d.add(
    NodeGroup(title="ZodStringFormat<Format> Subclasses", padding=4.5),
    xy=(102.0, 4.0),
)
g_fmt.add(
    Node("ZodEmail / ZodUUID / ULID\nz.email() / z.uuid() / z.cuid2()", width=66, height=12.5, icon=PhosphorIcon.FINGERPRINT, icon_size=5.5, style=Styles.WhiteBold, text_style=Styles.WhiteBold.patch(text_size=10.0), card_style=Styles.AccentFlat),
    xy=(37.5, 49.0),
)
g_fmt.add(
    Node("ZodURL / ZodIPv4 / ZodIPv6\nz.url() / z.httpUrl() / z.cidrv4()", width=66, height=12.5, icon=PhosphorIcon.GLOBE, icon_size=5.5, card_style=Styles.PrimaryNeutral),
    xy=(37.5, 34.0),
)
g_fmt.add(
    Node("ZodJWT / ZodBase64 / Hash\nz.jwt() / z.base64url() / z.hash()", width=66, height=12.5, icon=PhosphorIcon.SHIELD_CHECK, icon_size=5.5, card_style=Styles.Neutral),
    xy=(37.5, 19.0),
)
g_fmt.add(
    Node("ZodISODateTime / Date / Time\nz.iso.datetime() / date / duration", width=66, height=12.5, icon=PhosphorIcon.CLOCK, icon_size=5.5, card_style=Styles.PrimaryNeutral),
    xy=(37.5, 4.0),
)

d.draw(xy=(4.0, 2.0))

# Top-down tree bus from ZodType root (center x=92, bottom y=79.5) to the top of each group (y=68.5)
line((92.0, 79.5), (92.0, 74.5), style=Styles.PrimaryBold)
line((28.5, 74.5), (143.5, 74.5), style=Styles.PrimaryBold)
line((28.5, 74.5), (28.5, 68.5), arrow_head="->", style=Styles.PrimaryBold)
line((78.5, 74.5), (78.5, 68.5), arrow_head="->", style=Styles.PrimaryBold)
line((143.5, 74.5), (143.5, 68.5), arrow_head="->", style=Styles.PrimaryBold)

canvas.save()

functionz.string#

Constructs a ZodString schema that validates typeof input === "string". Includes built-in length checks, substring/regex validators, and in-place string normalization transforms.

function z.string(params?: string | core.$ZodStringParams): ZodString

import { z } from "zod";

const Username = z
  .string("Username is required")
  .trim()
  .toLowerCase()
  .min(3, "Must be at least 3 chars")
  .max(24)
  .regex(/^[a-z0-9_]+$/, "Only lowercase letters, digits, and underscores");

Username.parse("  Alice_42 "); // => "alice_42"

functionz.number#

Constructs a ZodNumber schema that validates finite IEEE-754 floating-point numbers (typeof input === "number" && Number.isFinite(input)). Unlike Zod v3, Infinity, -Infinity, and NaN are rejected by default.

function z.number(params?: string | core.$ZodNumberParams): ZodNumber

import { z } from "zod";

const Price = z.number().nonnegative().multipleOf(0.01);
Price.parse(19.99); // => 19.99
Price.safeParse(Number.POSITIVE_INFINITY).success; // => false

functionz.int#

Constructs a ZodNumberFormat schema restricting numbers to specific integer or IEEE-754 bit-width ranges and emitting a matching format in JSON Schema.

function z.int(params?: string | core.$ZodCheckNumberFormatParams): ZodInt
function z.int32(params?: string | core.$ZodCheckNumberFormatParams): ZodInt32
function z.uint32(params?: string | core.$ZodCheckNumberFormatParams): ZodUInt32
function z.float32(params?: string | core.$ZodCheckNumberFormatParams): ZodFloat32
function z.float64(params?: string | core.$ZodCheckNumberFormatParams): ZodFloat64

import { z } from "zod";

const Port = z.uint32().min(1024).max(65535);
Port.parse(8080); // => 8080

functionz.bigint#

Constructs a ZodBigInt schema validating typeof input === "bigint", along with 64-bit signed (z.int64) and unsigned (z.uint64) format constructors.

function z.bigint(params?: string | core.$ZodBigIntParams): ZodBigInt
function z.int64(params?: string | core.$ZodBigIntFormatParams): ZodInt64
function z.uint64(params?: string | core.$ZodBigIntFormatParams): ZodUInt64

import { z } from "zod";

const SnowflakeId = z.uint64();
SnowflakeId.parse(175928847299117063n);

functionz.boolean#

Constructs a ZodBoolean schema that strictly validates typeof input === "boolean".

function z.boolean(params?: string | core.$ZodBooleanParams): ZodBoolean

import { z } from "zod";

const IsActive = z.boolean("Active flag must be a boolean");
IsActive.parse(true); // => true

functionz.stringbool#

Constructs a bidirectional ZodCodec<ZodString, ZodBoolean> that decodes environment-variable style boolean strings ("true", "1", "yes", "on", "false", "0", "no", "off") into boolean and encodes boolean back to the primary truthy/falsy string ("true" / "false").

function z.stringbool(params?: string | core.$ZodStringBoolParams): ZodCodec<ZodString, ZodBoolean>

import { z } from "zod";

const EnvFlag = z.stringbool({ truthy: ["true", "1"], falsy: ["false", "0"] });

EnvFlag.parse("1"); // => true
EnvFlag.encode(false); // => "false"

functionz.date#

Constructs a ZodDate schema validating input instanceof Date && !Number.isNaN(input.getTime()). Rejects Invalid Date instances.

function z.date(params?: string | core.$ZodDateParams): ZodDate

import { z } from "zod";

constLaunchDate = z.date().min(new Date("2025-01-01T00:00:00Z"));

functionz.literal#

Constructs a ZodLiteral<T> schema matching one or more exact primitive values (string | number | bigint | boolean | null | undefined). In Zod v4, passing an array of literals z.literal(["a", "b"]) creates a single O(1) Set-backed ZodLiteral instead of requiring z.union().

function z.literal<const T extends util.Literal>(value: T, params?: string | core.$ZodLiteralParams): ZodLiteral<T>
function z.literal<const T extends ReadonlyArray<util.Literal>>(values: T, params?: string | core.$ZodLiteralParams): ZodLiteral<T[number]>

import { z } from "zod";

const HttpStatus = z.literal([200, 201, 204]);
type Status = z.infer<typeof HttpStatus>; // 200 | 201 | 204

functionz.enum#

Constructs a ZodEnum<T> schema from either a readonly string[] tuple or a TypeScript enum / const object (unifying Zod v3's z.enum() and z.nativeEnum()).

function z.enum<const T extends readonly string[]>(values: T, params?: string | core.$ZodEnumParams): ZodEnum<util.ToEnum<T[number]>>
function z.enum<const T extends util.EnumLike>(entries: T, params?: string | core.$ZodEnumParams): ZodEnum<T>

import { z } from "zod";

const Role = z.enum(["admin", "editor", "viewer"]);
const StaffRole = Role.exclude(["viewer"]); // ZodEnum<{ admin: "admin"; editor: "editor" }>

functionz.templateLiteral#

Constructs a ZodTemplateLiteral<Template> schema that compiles an array of literal primitives and inner schemas (z.string(), z.number(), z.int(), z.boolean(), z.literal(), z.enum(), etc.) into an exact TypeScript template literal type and composite regular expression.

function z.templateLiteral<const Parts extends core.$ZodTemplateLiteralPart[]>(
  parts: Parts,
  params?: string | core.$ZodTemplateLiteralParams
): ZodTemplateLiteral<core.$PartsToTemplateLiteral<Parts>>

import { z } from "zod";

const CssUnit = z.templateLiteral([z.number(), z.enum(["px", "rem", "vh", "vw"])]);
type CssUnit = z.infer<typeof CssUnit>; // `${number}px` | `${number}rem` | `${number}vh` | `${number}vw`

CssUnit.parse("16px"); // => "16px"

namespace z.coerce#

The z.coerce namespace provides primitive constructors that coerce unknown input via JavaScript's built-in constructor (String(x), Number(x), Boolean(x), BigInt(x), new Date(x)) before running schema validation. In Zod v4, the inferred input type z.input<typeof schema> defaults to unknown (and can be explicitly parameterized via z.coerce.number<string | number>()).

namespace z.coerce {
  function string<T = unknown>(params?: string | core.$ZodStringParams): ZodCoercedString<T>;
  function number<T = unknown>(params?: string | core.$ZodNumberParams): ZodCoercedNumber<T>;
  function boolean<T = unknown>(params?: string | core.$ZodBooleanParams): ZodCoercedBoolean<T>;
  function bigint<T = unknown>(params?: string | core.$ZodBigIntParams): ZodCoercedBigInt<T>;
  function date<T = unknown>(params?: string | core.$ZodDateParams): ZodCoercedDate<T>;
}

import { z } from "zod";

const PageQuery = z.coerce.number<string | number>().int().min(1);
PageQuery.parse("42"); // => 42

functionz.email#

In Zod v4, string formats are promoted to first-class top-level constructors returning subclasses of ZodStringFormat<Format> for optimal tree-shaking and clean type hierarchy.

from drawlib.canvas import save, setup
from drawlib.smartarts import Table
from drawlib.styles import Colors, Styles
from drawlib.text import text

setup(width=186, height=90, dpi=150)

text(
    (93, 85.5),
    "Zod v4.6.7 Top-Level String Format & z.iso.* Constructors",
    style=Styles.DarkBold.patch(text_size=12.5),
)

table = Table(
    cell_style=Styles.White,
    text_style=Styles.Dark.patch(text_size=10.0),
    header_cell_style=Styles.PrimaryFlat,
    header_text_style=Styles.WhiteBold.patch(text_size=10.5),
    border_style=Styles.MutedThin,
)

table.set_style_cell_evenodd(
    even_color=Colors.Light,
    even_text_style=Styles.Dark.patch(text_size=10.0),
    odd_color=Colors.White,
    odd_text_style=Styles.Dark.patch(text_size=10.0),
)
table.set_style_cell_header(
    background_color=Colors.Primary,
    text_style=Styles.WhiteBold.patch(text_size=10.5),
)
table.set_style_cell(
    background_color=Colors.Light,
    text_style=Styles.PrimaryBold.patch(text_size=10.0),
    rows=[1, 2, 3, 4, 5, 6, 7, 8, 9],
    columns=[0],
)

data = [
    ["Constructor", "Return Class", "Format Options (params)", "JSON Schema format"],
    ["z.email(params?)", "ZodEmail", "pattern?: RegExp (gmail/html5/rfc5322)", '"email"'],
    ["z.uuid() / z.uuidv4..v7()", "ZodUUID", 'version?: "v1".."v8" (RFC 9562)', '"uuid"'],
    ["z.nanoid / cuid2 / ulid", "ZodNanoID / CUID2 / ULID", "length?: number (on z.nanoid)", '"nanoid" / "cuid2" / "ulid"'],
    ["z.url() / z.httpUrl()", "ZodURL", "protocol?: RegExp, hostname?: RegExp, normalize?", '"uri"'],
    ["z.jwt(params?)", "ZodJWT", 'alg?: JWTAlgorithm ("HS256", "RS256", ...)', '"jwt"'],
    ["z.ipv4() / z.ipv6() / cidr*", "ZodIPv4 / IPv6 / CIDR*", "Strict IPv4/IPv6 & CIDR prefix validation", '"ipv4" / "ipv6" / "cidrv4"'],
    ["z.hash(alg, params?)", "ZodCustomStringFormat", 'alg: "md5"|"sha1"|"sha256"|"sha384"|"sha512", enc?', '"<alg>_<enc>"'],
    ["z.iso.datetime(params?)", "ZodISODateTime", "offset?: bool, local?: bool, precision?: number", '"date-time"'],
    ["z.iso.date / time / duration", "ZodISODate / Time / Duration", "precision?: number (on z.iso.time)", '"date" / "time" / "duration"'],
]

table.draw_flexible(
    xy=(4, 80),
    column_widths=[38, 36, 68, 36],
    row_heights=[8.0, 7.2, 7.2, 7.2, 7.2, 7.2, 7.2, 7.2, 7.2, 7.2],
    data=data,
    align="top_left",
)

save()

z.email() validates email addresses and allows overriding the regex pattern via z.regexes.*:

function z.email(params?: string | core.$ZodEmailParams): ZodEmail

import { z } from "zod";

const CorpEmail = z.email({ pattern: z.regexes.html5Email });

functionz.uuid#

Validates RFC 9562 / RFC 4122 UUID strings and related distributed identifier formats (guid, nanoid, cuid2, ulid, xid, ksuid).

function z.uuid(params?: string | core.$ZodUUIDParams): ZodUUID
function z.uuidv4(params?: string | core.$ZodUUIDv4Params): ZodUUID
function z.uuidv6(params?: string | core.$ZodUUIDv6Params): ZodUUID
function z.uuidv7(params?: string | core.$ZodUUIDv7Params): ZodUUID
function z.guid(params?: string | core.$ZodGUIDParams): ZodGUID
function z.nanoid(params?: string | core.$ZodNanoIDParams): ZodNanoID
function z.cuid2(params?: string | core.$ZodCUID2Params): ZodCUID2
function z.ulid(params?: string | core.$ZodULIDParams): ZodULID
function z.xid(params?: string | core.$ZodXIDParams): ZodXID
function z.ksuid(params?: string | core.$ZodKSUIDParams): ZodKSUID

import { z } from "zod";

const EventId = z.uuidv7();
const ShortId = z.nanoid({ length: 12 });

functionz.url#

Validates URLs using the WHATWG URL parser with optional protocol and hostname regular expression guards and optional WHATWG .href normalization. z.httpUrl() pre-configures protocol: /^https?$/i and hostname: z.regexes.domain for web URLs.

function z.url(params?: string | core.$ZodURLParams): ZodURL
function z.httpUrl(params?: string | Omit<core.$ZodURLParams, "protocol" | "hostname">): ZodURL

import { z } from "zod";

const WebhookUrl = z.url({
  protocol: /^https$/,
  hostname: z.regexes.domain,
  normalize: true,
});

functionz.jwt#

Validates JSON Web Tokens (3-part base64url structure with valid JSON header and alg claim), alongside encoding, cryptographic hash, and telecom/finance string formats.

function z.jwt(params?: string | core.$ZodJWTParams): ZodJWT
function z.base64(params?: string | core.$ZodBase64Params): ZodBase64
function z.base64url(params?: string | core.$ZodBase64URLParams): ZodBase64URL
function z.hex(params?: string | core.$ZodStringFormatParams): ZodCustomStringFormat<"hex">
function z.hash<Alg extends util.HashAlgorithm, Enc extends util.HashEncoding = "hex">(
  alg: Alg,
  params?: { enc?: Enc } & core.$ZodStringFormatParams
): ZodCustomStringFormat<`${Alg}_${Enc}`>
function z.e164(params?: string | core.$ZodE164Params): ZodE164
function z.creditCard(params?: string | core.$ZodCreditCardParams): ZodCreditCard
function z.iban(params?: string | core.$ZodIBANParams): ZodIBAN

import { z } from "zod";

const BearerJwt = z.jwt({ alg: "RS256" });
const CommitSha256 = z.hash("sha256", { enc: "hex" });

functionz.ipv4 & z.ipv6#

Validates network addresses, CIDR blocks, MAC addresses, and DNS hostnames:

function z.ipv4(params?: string | core.$ZodIPv4Params): ZodIPv4
function z.ipv6(params?: string | core.$ZodIPv6Params): ZodIPv6
function z.cidrv4(params?: string | core.$ZodCIDRv4Params): ZodCIDRv4
function z.cidrv6(params?: string | core.$ZodCIDRv6Params): ZodCIDRv6
function z.mac(params?: string | core.$ZodMACParams): ZodMAC
function z.hostname(params?: string | core.$ZodStringFormatParams): ZodCustomStringFormat<"hostname">
function z.stringFormat<Format extends string>(
  format: Format,
  fnOrRegex: ((arg: string) => util.MaybeAsync<unknown>) | RegExp,
  params?: string | core.$ZodStringFormatParams
): ZodCustomStringFormat<Format>

import { z } from "zod";

const Subnet = z. union([z.cidrv4(), z.cidrv6()]);
const MacColon = z.mac({ delimiter: ":" });

namespace z.iso#

The z.iso namespace provides strict ISO 8601 date, time, datetime, and duration string schemas (ZodISODateTime, ZodISODate, ZodISOTime, ZodISODuration).

namespace z.iso {
  function datetime(params?: string | core.$ZodISODateTimeParams): ZodISODateTime;
  function date(params?: string | core.$ZodISODateParams): ZodISODate;
  function time(params?: string | core.$ZodISOTimeParams): ZodISOTime;
  function duration(params?: string | core.$ZodISODurationParams): ZodISODuration;
}

import { z } from "zod";

const Timestamp = z.iso.datetime({ offset: true, precision: z.TimePrecision.Millisecond });
Timestamp.parse("2026-11-10T10:30:00.123+09:00");

functionz.any / z.unknown / z.never / z.void / z.nan#

Special-purpose bottom, top, unit, symbol, and Web File schemas:

function z.any(): ZodAny
function z.unknown(): ZodUnknown
function z.never(params?: string | core.$ZodNeverParams): ZodNever
function z.void(params?: string | core.$ZodVoidParams): ZodVoid
function z.undefined(params?: string | core.$ZodUndefinedParams): ZodUndefined
function z.null(params?: string | core.$ZodNullParams): ZodNull
function z.nan(params?: string | core.$ZodNaNParams): ZodNaN
function z.symbol(params?: string | core.$ZodSymbolParams): ZodSymbol
function z.file(params?: string | core.$ZodFileParams): ZodFile

import { z } from "zod";

const AvatarUpload = z
  .file()
  .min(1024)
  .max(5 * 1024 * 1024)
  .mime(["image/png", "image/webp"]);