0
# ISO DateTime Schemas
1

2
ISO 8601 date/time string validators for datetime, date, time, and duration formats.
3

4
## ISO Namespace
5

6
```typescript { .api }
7
namespace iso {
8
  function datetime(params?: ISODateTimeParams): ZodISODateTime;
9
  function date(params?: ISOParams): ZodISODate;
10
  function time(params?: ISOParams): ZodISOTime;
11
  function duration(params?: ISOParams): ZodISODuration;
12
}
13

14
interface ISODateTimeParams {
15
  precision?: number;
16
  offset?: boolean;
17
  local?: boolean;
18
  description?: string;
19
  errorMap?: ZodErrorMap;
20
}
21

22
interface ISOParams {
23
  description?: string;
24
  errorMap?: ZodErrorMap;
25
}
26
```
27

28
## ISO DateTime
29

30
```typescript
31
z.iso.datetime()
32
// Validates ISO 8601 datetime strings
33

34
z.iso.datetime().parse("2024-01-01T12:00:00Z");           // Valid
35
z.iso.datetime().parse("2024-01-01T12:00:00.123Z");       // Valid
36
z.iso.datetime().parse("2024-01-01T12:00:00+05:30");      // Valid
37

38
// With precision
39
z.iso.datetime({ precision: 3 })  // Millisecond precision
40
z.iso.datetime({ precision: 0 })  // No fractional seconds
41

42
// Offset handling
43
z.iso.datetime({ offset: true })   // Require timezone offset
44
z.iso.datetime({ offset: false })  // Disallow timezone offset
45
z.iso.datetime({ local: true })    // Local time (no Z or offset)
46

47
// Examples
48
z.iso.datetime({ precision: 3 }).parse("2024-01-01T12:00:00.123Z");  // Valid
49
z.iso.datetime({ offset: false }).parse("2024-01-01T12:00:00");      // Valid
50
z.iso.datetime({ local: true }).parse("2024-01-01T12:00:00");        // Valid
51
```
52

53
## ISO Date
54

55
```typescript
56
z.iso.date()
57
// Validates ISO 8601 date strings (YYYY-MM-DD)
58

59
z.iso.date().parse("2024-01-01");  // Valid
60
z.iso.date().parse("2024-12-31");  // Valid
61
z.iso.date().parse("2024/01/01");  // Invalid
62
```
63

64
## ISO Time
65

66
```typescript
67
z.iso.time()
68
// Validates ISO 8601 time strings (HH:mm:ss or HH:mm:ss.SSS)
69

70
z.iso.time().parse("12:00:00");       // Valid
71
z.iso.time().parse("23:59:59");       // Valid
72
z.iso.time().parse("12:00:00.123");   // Valid
73
z.iso.time().parse("12:00:00Z");      // Valid (with timezone)
74
z.iso.time().parse("12:00:00+05:30"); // Valid (with offset)
75
```
76

77
## ISO Duration
78

79
```typescript
80
z.iso.duration()
81
// Validates ISO 8601 duration strings (PnYnMnDTnHnMnS)
82

83
z.iso.duration().parse("P1Y");           // 1 year
84
z.iso.duration().parse("P1M");           // 1 month
85
z.iso.duration().parse("P1D");           // 1 day
86
z.iso.duration().parse("PT1H");          // 1 hour
87
z.iso.duration().parse("PT1M");          // 1 minute
88
z.iso.duration().parse("PT1S");          // 1 second
89
z.iso.duration().parse("P1Y2M3DT4H5M6S"); // Combined
90
z.iso.duration().parse("PT30M");         // 30 minutes
91
```
92

93
## Common Patterns
94

95
```typescript
96
// Event schema
97
const EventSchema = z.object({
98
  id: z.string().uuid(),
99
  title: z.string(),
100
  startTime: z.iso.datetime(),
101
  endTime: z.iso.datetime(),
102
  date: z.iso.date(),
103
});
104

105
// API timestamp fields
106
const APISchema = z.object({
107
  createdAt: z.iso.datetime(),
108
  updatedAt: z.iso.datetime(),
109
  publishDate: z.iso.date().optional(),
110
});
111

112
// Schedule
113
const ScheduleSchema = z.object({
114
  date: z.iso.date(),
115
  startTime: z.iso.time(),
116
  endTime: z.iso.time(),
117
  duration: z.iso.duration().optional(),
118
});
119

120
// Meeting
121
const MeetingSchema = z.object({
122
  title: z.string(),
123
  scheduledAt: z.iso.datetime({ offset: true }),
124
  duration: z.iso.duration(),
125
  timezone: z.string(),
126
});
127

128
// Log entry
129
const LogSchema = z.object({
130
  timestamp: z.iso.datetime({ precision: 3 }),
131
  level: z.enum(["info", "warn", "error"]),
132
  message: z.string(),
133
});
134
```
135

136
## Transformation to Date Objects
137

138
```typescript
139
// Parse ISO string and convert to Date
140
const DateTimeSchema = z.iso.datetime().transform((str) => new Date(str));
141

142
const result = DateTimeSchema.parse("2024-01-01T12:00:00Z");
143
// result is a Date object
144

145
// With validation
146
const FutureDateSchema = z.iso.datetime()
147
  .transform((str) => new Date(str))
148
  .refine((date) => date > new Date(), "Must be in the future");
149

150
// Combined schema
151
const EventWithDatesSchema = z.object({
152
  name: z.string(),
153
  startDate: z.iso.datetime().transform((s) => new Date(s)),
154
  endDate: z.iso.datetime().transform((s) => new Date(s)),
155
}).refine(
156
  (data) => data.endDate > data.startDate,
157
  { message: "End date must be after start date", path: ["endDate"] }
158
);
159
```
160

161
## ISO vs Date Schema
162

163
```typescript
164
// ISO datetime string
165
z.iso.datetime()
166
// Input: "2024-01-01T12:00:00Z" (string)
167
// Output: "2024-01-01T12:00:00Z" (string)
168

169
// Date object
170
z.date()
171
// Input: Date object
172
// Output: Date object
173

174
// Coerced date
175
z.coerce.date()
176
// Input: anything (string, number, Date)
177
// Output: Date object
178

179
// ISO with transformation
180
z.iso.datetime().transform((s) => new Date(s))
181
// Input: "2024-01-01T12:00:00Z" (string)
182
// Output: Date object
183
```
184