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

> Master Zod's ISO date and time schemas, including z.datetime(), z.date(), z.time(), and z.duration(). Validate temporal data efficiently with this comprehensive guide.

- Repository: [Colin McDonnell/zod](https://github.com/colinhacks/zod)
- Tags: how-to-guide
- Published: 2026-02-23

---

**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`](https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/classic/iso.ts) delegate to core validation primitives in [`packages/zod/src/v4/core/api.ts`](https://github.com/colinhacks/zod/blob/main/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`](https://github.com/colinhacks/zod/blob/main/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`](https://github.com/colinhacks/zod/blob/main/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:

```typescript
// 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`](https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/api.ts), where helpers construct schema instances with standardized format identifiers:

```typescript
// 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:

```typescript
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`](https://github.com/colinhacks/zod/blob/main/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

```typescript
// 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`](https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/classic/iso.ts) while core logic resides in [`packages/zod/src/v4/core/api.ts`](https://github.com/colinhacks/zod/blob/main/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`](https://github.com/colinhacks/zod/blob/main/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`](https://github.com/colinhacks/zod/blob/main/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`](https://github.com/colinhacks/zod/blob/main/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`](https://github.com/colinhacks/zod/blob/main/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`](https://github.com/colinhacks/zod/blob/main/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`](https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/api.ts). The schemas are ultimately exposed through the main entry point at [`packages/zod/src/v4/index.ts`](https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/index.ts).