API input validation
Validate API payload timestamps before processing them.
Zod · Module
.datetime
z.iso.datetime() validates strings against a strict subset of ISO 8601. Timezone offsets are rejected by default and can be enabled with { offset: true }.
How it works
z.iso.datetime() validates strings against Zod's supported ISO 8601 datetime format. It rejects timezone offsets by default, while the offset option enables them; the schema can then parse valid strings and reject invalid ones.
Syntax
z.iso.datetime(options?)Parameters
| Name | Type | Description |
|---|---|---|
options | object | Options object; the documented offset: true setting permits timezone offsets. |
Returns
A Zod ISO datetime string schema.
Key points
- Use
z.iso.datetime()for Zod's strict ISO 8601 datetime-string format rather than treating every ISO 8601 variant as valid. - A UTC datetime ending in
Zis accepted by the default schema. - Fractional seconds may use arbitrary precision in the documented datetime examples.
- Configure the schema with
offset: truewhen inputs may contain timezone offsets. - The extended offset form
+02:00is accepted when offset support is enabled.
Common mistakes
- Timezone offsets are rejected unless the
offsetoption is enabled. - Enabling offsets does not make shortened forms such as
+02or+0200valid. - A datetime without a timezone marker is rejected by the default schema.
Example: Accept an ISO datetime with an offset
import { z } from "zod";
const datetime = z.iso.datetime({ offset: true });
console.log(datetime.parse("2020-01-01T06:15:00+02:00"));
Creates an ISO datetime schema that accepts a timezone offset, then parses a matching string.
When to use it
Canonical timestamp storage
Require UTC-marked timestamps for persisted records.
Offset-aware input
Accept client timestamps that include explicit numeric offsets.
Interview questions
QWhat does z.iso.datetime() validate by default?
It validates an input string against Zod's supported ISO 8601 datetime format. The default form accepts a Z timezone marker but does not accept timezone offsets.
Follow-up: How would you accept an offset such as +02:00? Use z.iso.datetime({ offset: true }), while still rejecting the basic offset forms +02 and +0200.
QHow do you allow timezone offsets?
Pass { offset: true } to the factory: z.iso.datetime({ offset: true }). This allows timezone offsets such as +02:00, and Z remains valid.
Follow-up: What happens to a local datetime such as 2020-01-01T06:15:00? It remains invalid because the documented schema requires a timezone designator.
QWhich precision and timezone forms are demonstrated as valid or invalid?
A string with arbitrary fractional-second precision, such as .123456, is accepted by the documented examples. A timezone-less local datetime is not accepted by the default schema.
Follow-up: Can +0200 be used when offsets are enabled? No; the documentation specifically shows that only the colon form +02:00 is accepted among those examples.
Related
z.iso.date()z.iso.duration()z.codec()z.date()