Zod · Module

z.iso.date

z.iso.date() validates strings in the YYYY-MM-DD format and rejects malformed or impossible calendar dates. Use z.date() for JavaScript Date instances.

How it works

Call z.iso.date() to create a schema for strings written as four-digit year, two-digit month, and two-digit day. Parsing accepts a valid calendar date and rejects malformed or impossible dates; use z.date() instead when the input should be a JavaScript Date instance.

Syntax

z.iso.date();

Returns

A Zod schema that validates ISO calendar-date strings.

Key points

It is a string schema for the four-digit-year, two-digit-month, two-digit-day format.
A properly formatted valid calendar date parses successfully.
The month and day must use two digits rather than abbreviated numeric components.
Calendar validity is checked, so an impossible day is rejected.
It belongs to Zod’s ISO-focused helpers alongside time, datetime, and duration schemas.

Common mistakes

This schema validates strings, not JavaScript Date objects; use z.date() for Date instances.
Single-digit month or day components do not satisfy the required format.
The date must be a real calendar date, not merely a text string matching the shape.

Example: Validate an ISO calendar date

import { z } from "zod";

const date = z.iso.date();

console.log(date.parse("2020-01-01"));
// date.parse("2020-1-1");  // throws
// date.parse("2020-01-32"); // throws

Creates an ISO calendar-date schema and parses a valid YYYY-MM-DD string.

When to use it

API date input

Validate request, form, or configuration fields that carry dates as text.

Canonical date strings

Enforce a stable, zero-padded calendar-date representation before persistence or processing.

Type distinction

Keep date-only values separate from timestamps and JavaScript Date objects.

Interview questions

QWhat does z.iso.date() validate?

z.iso.date() returns a Zod schema that validates ISO-style calendar-date strings in YYYY-MM-DD form. Its parser accepts values such as 2020-01-01.

Follow-up: How would you validate a JavaScript Date instead? Use z.date(), because z.iso.date() is for strings.

QWhich inputs are rejected?

It requires fixed-width year, month, and day components: 2020-01-01 is valid, while 2020-1-1 is not. It also rejects impossible dates such as 2020-01-32.

Follow-up: What additional distinction should an API designer make? Choose z.iso.datetime() when the value must include a date and time rather than only a calendar date.

QDoes it produce a Date instance?

Parsing with date.parse(value) returns the validated string when successful and throws when validation fails. The schema does not convert the string into a Date object.

Follow-up: How can a conversion be modeled? Compose an appropriate input schema with a codec or transformation when a Date object is required.

z.iso.time
z.iso.datetime
z.iso.duration
z.date

Source: Defining schemas | Zod. Checked 2026-10-15.