How to Use Zod's ISO Date/Time Schemas: Complete Guide to z.datetime(), z.date(), z.time(), and z.duration()

Zod provides native ISO-8601 validation through z.datetime(), z.date(), z.time(), and z.duration() factories that internally use core string-format helpers to validate temporal data according to the ISO-8601 specification.

Zod's ISO date/time schemas enable strict type-safe validation of temporal strings without requiring external date libraries. Built into the colinhacks/zod repository, these schemas leverage a dual-layer architecture where public factory functions in packages/zod/src/v4/classic/iso.ts delegate to core validation primitives in packages/zod/src/v4/core/api.ts. Understanding these ISO schemas ensures your applications handle calendar dates, timestamps, and durations with precise format compliance.

Available ISO Date/Time Schema Types

Zod exposes four distinct factory functions for ISO-8601 validation, each targeting a specific temporal representation:

• z.datetime() – Validates full ISO-8601 datetime strings including offsets (YYYY-MM-DDTHH:mm:ss.sssZ)
• z.date() – Validates calendar dates in YYYY-MM-DD format
• z.time() – Validates time-of-day strings with optional offsets (HH:mm:ss.sss)
• z.duration() – Validates ISO-8601 duration strings (PnDTnHnM...)

These factories are re-exported from the main entry point at packages/zod/src/v4/index.ts, making them available immediately upon importing the z object.

Factory Implementation and Core Architecture

The public API resides in packages/zod/src/v4/classic/iso.ts, where each factory serves as a thin wrapper around core validation helpers.

Public Factory Functions

Each factory forwards parameters to its corresponding core helper while passing the appropriate constructor class:

// packages/zod/src/v4/classic/iso.ts
export function datetime(params?: string | core.$ZodISODateTimeParams): ZodISODateTime {
  return core._isoDateTime(ZodISODateTime, params);
}

Similar implementations exist for date(), time(), and duration(), each calling core._isoDate(), core._isoTime(), and core._isoDuration() respectively.

Core Helper Implementation

The underlying logic lives in packages/zod/src/v4/core/api.ts, where helpers construct schema instances with standardized format identifiers:

// packages/zod/src/v4/core/api.ts
export function _isoDateTime<T extends schemas.$ZodISODateTime>(
  Class: util.SchemaClass<T>,
  params?: string | $ZodISODateTimeParams | $ZodCheckISODateTimeParams
): T {
  return new Class({
    type: "string",
    format: "datetime",
    check: "string_format",
    offset: false,
    local: false,
    precision: null,
    ...util.normalizeParams(params),
  });
}

This pattern ensures consistent validation behavior while allowing parameter overrides for offset, local, and precision settings.

Validating ISO-8601 Strings

The following examples demonstrate practical validation using Zod's ISO date/time schemas:

import { z } from "zod";

// 1. Full ISO datetime validation
const DateTimeSchema = z.datetime();
DateTimeSchema.parse("2024-03-15T13:45:30Z"); // ✓ passes
DateTimeSchema.parse("2024-03-15T13:45:30+02:00"); // ✓ passes with offset

// 2. Calendar date only
const DateSchema = z.date();
DateSchema.parse("2024-03-15"); // returns "2024-03-15"

// 3. Time of day with optional offset
const TimeSchema = z.time();
TimeSchema.parse("23:59:59.999"); // ✓ passes
TimeSchema.parse("13:45:30+02:00"); // ✓ passes with offset

// 4. ISO-8601 duration
const DurationSchema = z.duration();
DurationSchema.parse("P1Y2M3DT4H5M6S"); // ✓ passes
DurationSchema.parse("P3DT4H5M6S"); // ✓ passes

// 5. Strict UTC requirement (no offsets, no local time)
const StrictUTC = z.datetime({ offset: false, local: false });

Customizing Validation Parameters

All ISO factories accept a configuration object implementing the $Zod*Params types defined in core/api.ts. Key parameters include:

• precision – Controls fractional second precision (null for any, 0 for seconds only, positive integers for millisecond precision)
• offset – Boolean indicating whether timezone offsets are permitted
• local – Boolean indicating whether local time (without timezone) is permitted

// Restrict to second-level precision only
const PreciseDateTime = z.datetime({ precision: 0 });
PreciseDateTime.safeParse("2024-03-15T13:45:30.123Z"); // returns { success: false }

// Allow local time but require offsets when specified
const FlexibleTime = z.time({ local: true, offset: true });

Summary

• Four Factories: Use z.datetime(), z.date(), z.time(), and z.duration() for comprehensive ISO-8601 validation
• Source Locations: Factory functions live in packages/zod/src/v4/classic/iso.ts while core logic resides in packages/zod/src/v4/core/api.ts
• Parameter Control: Customize validation through precision, offset, and local options passed to any factory
• String-Based: These schemas validate string representations, not native JavaScript Date objects
• Top-Level Access: Import from zod directly; functions are re-exported through packages/zod/src/v4/index.ts

Frequently Asked Questions

What is the difference between z.date() and z.datetime() in Zod?

z.date() validates ISO-8601 calendar date strings in YYYY-MM-DD format only, while z.datetime() validates complete timestamps including time components and timezone offsets (YYYY-MM-DDTHH:mm:ss.sssZ). According to the source in packages/zod/src/v4/classic/iso.ts, they map to different core helpers (_isoDate vs _isoDateTime) with distinct regex patterns and format identifiers.

How do I require UTC timestamps only without offsets?

Pass { offset: false, local: false } to z.datetime(). As implemented in packages/zod/src/v4/core/api.ts, these parameters configure the underlying schema to reject strings containing timezone offsets (like +02:00) and local time representations, enforcing strict UTC formatting with the Z suffix.

Can I customize the precision of datetime validation in Zod?

Yes, use the precision parameter. Set precision: 0 to allow only second-level precision (no fractional seconds), or specify a positive integer to limit millisecond digits. The default precision: null accepts any precision level. This parameter is processed in the _isoDateTime helper within packages/zod/src/v4/core/api.ts.

Where are the ISO date/time schemas implemented in the Zod source code?

The public API is defined in packages/zod/src/v4/classic/iso.ts, which exports the four factory functions. These delegate to core implementation helpers (_isoDateTime, _isoDate, _isoTime, _isoDuration) located in packages/zod/src/v4/core/api.ts. The schemas are ultimately exposed through the main entry point at packages/zod/src/v4/index.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}