0
# String Format Schemas
1

2
Specialized string validators for common formats: emails, URLs, UUIDs, IP addresses, and ID formats.
3

4
## Email & URL
5

6
```typescript { .api }
7
/**
8
 * Create an email validation schema
9
 * @param params - Optional configuration with description and error map
10
 * @returns ZodEmail schema instance
11
 */
12
function email(params?: { description?: string; errorMap?: ZodErrorMap }): ZodEmail;
13

14
/**
15
 * Create a URL validation schema
16
 * @param params - Optional configuration with description and error map
17
 * @returns ZodURL schema instance
18
 */
19
function url(params?: { description?: string; errorMap?: ZodErrorMap }): ZodURL;
20

21
/**
22
 * Create an HTTP/HTTPS URL validation schema
23
 * @param params - Optional configuration with description and error map
24
 * @returns ZodURL schema instance restricted to HTTP(S)
25
 */
26
function httpUrl(params?: { description?: string; errorMap?: ZodErrorMap }): ZodURL;
27

28
interface ZodEmail extends ZodType<string, string> {
29
  // Inherits all ZodString methods
30
  min(length: number, params?: string | { message?: string }): this;
31
  max(length: number, params?: string | { message?: string }): this;
32
}
33

34
interface ZodURL extends ZodType<string, string> {}
35
```
36

37
**Examples:**
38
```typescript
39
const EmailSchema = z.email();
40
const result = EmailSchema.safeParse("user@example.com"); // success: true
41

42
// With additional constraints
43
const LimitedEmailSchema = z.email().max(255);
44

45
const URLSchema = z.url();
46
URLSchema.parse("https://example.com"); // Valid
47

48
const HTTPOnlySchema = z.httpUrl();
49
HTTPOnlySchema.parse("https://example.com"); // Valid
50
HTTPOnlySchema.parse("ftp://example.com"); // Invalid
51
```
52

53
## UUID & GUID
54

55
```typescript { .api }
56
/**
57
 * Create a UUID validation schema (any version)
58
 * @param params - Optional configuration with description and error map
59
 * @returns ZodUUID schema instance
60
 */
61
function uuid(params?: { description?: string; errorMap?: ZodErrorMap }): ZodUUID;
62

63
/**
64
 * Create a UUID v4 validation schema
65
 * @param params - Optional configuration with description and error map
66
 * @returns ZodUUID schema instance
67
 */
68
function uuidv4(params?: { description?: string; errorMap?: ZodErrorMap }): ZodUUID;
69

70
/**
71
 * Create a UUID v6 validation schema
72
 * @param params - Optional configuration with description and error map
73
 * @returns ZodUUID schema instance
74
 */
75
function uuidv6(params?: { description?: string; errorMap?: ZodErrorMap }): ZodUUID;
76

77
/**
78
 * Create a UUID v7 validation schema
79
 * @param params - Optional configuration with description and error map
80
 * @returns ZodUUID schema instance
81
 */
82
function uuidv7(params?: { description?: string; errorMap?: ZodErrorMap }): ZodUUID;
83

84
/**
85
 * Create a GUID validation schema
86
 * @param params - Optional configuration with description and error map
87
 * @returns ZodGUID schema instance
88
 */
89
function guid(params?: { description?: string; errorMap?: ZodErrorMap }): ZodGUID;
90

91
interface ZodUUID extends ZodType<string, string> {}
92
interface ZodGUID extends ZodType<string, string> {}
93
```
94

95
**Examples:**
96
```typescript
97
const UUIDSchema = z.uuid();
98
UUIDSchema.parse("550e8400-e29b-41d4-a716-446655440000"); // Valid
99

100
const UUIDv4Schema = z.uuidv4();
101
const UUIDv7Schema = z.uuidv7();
102
```
103

104
## IP Addresses
105

106
```typescript { .api }
107
/**
108
 * Create an IPv4 address validation schema
109
 * @param params - Optional configuration with description and error map
110
 * @returns ZodIPv4 schema instance
111
 */
112
function ipv4(params?: { description?: string; errorMap?: ZodErrorMap }): ZodIPv4;
113

114
/**
115
 * Create an IPv6 address validation schema
116
 * @param params - Optional configuration with description and error map
117
 * @returns ZodIPv6 schema instance
118
 */
119
function ipv6(params?: { description?: string; errorMap?: ZodErrorMap }): ZodIPv6;
120

121
/**
122
 * Create a CIDR v4 notation validation schema
123
 * @param params - Optional configuration with description and error map
124
 * @returns ZodCIDRv4 schema instance
125
 */
126
function cidrv4(params?: { description?: string; errorMap?: ZodErrorMap }): ZodCIDRv4;
127

128
/**
129
 * Create a CIDR v6 notation validation schema
130
 * @param params - Optional configuration with description and error map
131
 * @returns ZodCIDRv6 schema instance
132
 */
133
function cidrv6(params?: { description?: string; errorMap?: ZodErrorMap }): ZodCIDRv6;
134

135
interface ZodIPv4 extends ZodType<string, string> {}
136
interface ZodIPv6 extends ZodType<string, string> {}
137
interface ZodCIDRv4 extends ZodType<string, string> {}
138
interface ZodCIDRv6 extends ZodType<string, string> {}
139
```
140

141
**Examples:**
142
```typescript
143
const IPv4Schema = z.ipv4();
144
IPv4Schema.parse("192.168.1.1"); // Valid
145

146
const IPv6Schema = z.ipv6();
147
IPv6Schema.parse("2001:0db8:85a3:0000:0000:8a2e:0370:7334"); // Valid
148

149
const CIDRSchema = z.cidrv4();
150
CIDRSchema.parse("192.168.1.0/24"); // Valid
151
```
152

153
## Base64 & JWT
154

155
```typescript { .api }
156
/**
157
 * Create a base64 validation schema
158
 * @param params - Optional configuration with description and error map
159
 * @returns ZodBase64 schema instance
160
 */
161
function base64(params?: { description?: string; errorMap?: ZodErrorMap }): ZodBase64;
162

163
/**
164
 * Create a base64url validation schema
165
 * @param params - Optional configuration with description and error map
166
 * @returns ZodBase64URL schema instance
167
 */
168
function base64url(params?: { description?: string; errorMap?: ZodErrorMap }): ZodBase64URL;
169

170
/**
171
 * Create a JWT validation schema
172
 * @param params - Optional configuration with description and error map
173
 * @returns ZodJWT schema instance
174
 */
175
function jwt(params?: { description?: string; errorMap?: ZodErrorMap }): ZodJWT;
176

177
interface ZodBase64 extends ZodType<string, string> {}
178
interface ZodBase64URL extends ZodType<string, string> {}
179
interface ZodJWT extends ZodType<string, string> {}
180
```
181

182
**Examples:**
183
```typescript
184
const Base64Schema = z.base64();
185
Base64Schema.parse("SGVsbG8gV29ybGQ="); // Valid
186

187
const Base64URLSchema = z.base64url();
188

189
const JWTSchema = z.jwt();
190
JWTSchema.parse("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."); // Valid
191
```
192

193
## Phone & ID Formats
194

195
```typescript { .api }
196
/**
197
 * Create an E.164 phone number validation schema
198
 * @param params - Optional configuration with description and error map
199
 * @returns ZodE164 schema instance
200
 */
201
function e164(params?: { description?: string; errorMap?: ZodErrorMap }): ZodE164;
202

203
/**
204
 * Create a Nano ID validation schema
205
 * @param params - Optional configuration with description and error map
206
 * @returns ZodNanoID schema instance
207
 */
208
function nanoid(params?: { description?: string; errorMap?: ZodErrorMap }): ZodNanoID;
209

210
/**
211
 * Create a CUID validation schema
212
 * @param params - Optional configuration with description and error map
213
 * @returns ZodCUID schema instance
214
 */
215
function cuid(params?: { description?: string; errorMap?: ZodErrorMap }): ZodCUID;
216

217
/**
218
 * Create a CUID2 validation schema
219
 * @param params - Optional configuration with description and error map
220
 * @returns ZodCUID2 schema instance
221
 */
222
function cuid2(params?: { description?: string; errorMap?: ZodErrorMap }): ZodCUID2;
223

224
/**
225
 * Create a ULID validation schema
226
 * @param params - Optional configuration with description and error map
227
 * @returns ZodULID schema instance
228
 */
229
function ulid(params?: { description?: string; errorMap?: ZodErrorMap }): ZodULID;
230

231
/**
232
 * Create an XID validation schema
233
 * @param params - Optional configuration with description and error map
234
 * @returns ZodXID schema instance
235
 */
236
function xid(params?: { description?: string; errorMap?: ZodErrorMap }): ZodXID;
237

238
/**
239
 * Create a KSUID validation schema
240
 * @param params - Optional configuration with description and error map
241
 * @returns ZodKSUID schema instance
242
 */
243
function ksuid(params?: { description?: string; errorMap?: ZodErrorMap }): ZodKSUID;
244

245
interface ZodE164 extends ZodType<string, string> {}
246
interface ZodNanoID extends ZodType<string, string> {}
247
interface ZodCUID extends ZodType<string, string> {}
248
interface ZodCUID2 extends ZodType<string, string> {}
249
interface ZodULID extends ZodType<string, string> {}
250
interface ZodXID extends ZodType<string, string> {}
251
interface ZodKSUID extends ZodType<string, string> {}
252
```
253

254
**Examples:**
255
```typescript
256
const PhoneSchema = z.e164();
257
PhoneSchema.parse("+14155552671"); // Valid
258

259
const NanoIDSchema = z.nanoid();
260
const CUIDSchema = z.cuid();
261
const CUID2Schema = z.cuid2();
262
const ULIDSchema = z.ulid();
263
const XIDSchema = z.xid();
264
const KSUIDSchema = z.ksuid();
265
```
266

267
## Emoji & Custom Formats
268

269
```typescript { .api }
270
/**
271
 * Create an emoji validation schema
272
 * @param params - Optional configuration with description and error map
273
 * @returns ZodEmoji schema instance
274
 */
275
function emoji(params?: { description?: string; errorMap?: ZodErrorMap }): ZodEmoji;
276

277
/**
278
 * Create a hostname validation schema
279
 * @param params - Optional error message string or configuration parameters
280
 * @returns ZodCustomStringFormat for hostnames
281
 */
282
function hostname(params?: string | {
283
  message?: string;
284
  description?: string;
285
  errorMap?: ZodErrorMap
286
}): ZodCustomStringFormat<"hostname">;
287

288
/**
289
 * Create a hexadecimal string validation schema
290
 * @param params - Optional error message string or configuration parameters
291
 * @returns ZodCustomStringFormat for hex strings
292
 */
293
function hex(params?: string | {
294
  message?: string;
295
  description?: string;
296
  errorMap?: ZodErrorMap
297
}): ZodCustomStringFormat<"hex">;
298

299
/**
300
 * Create a hash format validation schema
301
 * @param alg - Hash algorithm type (e.g., "md5", "sha1", "sha256", "sha512")
302
 * @param params - Optional configuration with encoding and error parameters
303
 * @returns ZodCustomStringFormat with specific hash format type
304
 */
305
function hash<Alg extends HashAlgorithm, Enc extends HashEncoding = "hex">(
306
  alg: Alg,
307
  params?: {
308
    enc?: Enc;
309
    message?: string;
310
    description?: string;
311
    errorMap?: ZodErrorMap
312
  }
313
): ZodCustomStringFormat<`${Alg}_${Enc}`>;
314

315
/**
316
 * Create a custom string format validation schema with custom validation logic
317
 * @param format - Format name/identifier string
318
 * @param fnOrRegex - Validation function or regex pattern
319
 * @param params - Optional error message string or configuration parameters
320
 * @returns ZodCustomStringFormat schema instance
321
 */
322
function stringFormat<Format extends string>(
323
  format: Format,
324
  fnOrRegex: ((arg: string) => boolean | Promise<boolean>) | RegExp,
325
  params?: string | {
326
    message?: string;
327
    description?: string;
328
    errorMap?: ZodErrorMap
329
  }
330
): ZodCustomStringFormat<Format>;
331

332
type HashAlgorithm = "md5" | "sha1" | "sha256" | "sha384" | "sha512";
333
type HashEncoding = "hex" | "base64";
334

335
interface ZodEmoji extends ZodType<string, string> {}
336
interface ZodCustomStringFormat<Format extends string = string> extends ZodType<string, string> {}
337
```
338

339
**Examples:**
340
```typescript
341
const EmojiSchema = z.emoji();
342
EmojiSchema.parse("😀"); // Valid
343
EmojiSchema.parse("hello"); // Invalid
344

345
const HostnameSchema = z.hostname();
346
HostnameSchema.parse("example.com"); // Valid
347

348
const HexSchema = z.hex();
349
HexSchema.parse("1a2b3c"); // Valid
350

351
const MD5Schema = z.hash("md5");
352
const SHA256Schema = z.hash("sha256", { enc: "hex" });
353

354
// Custom format with regex
355
const CustomFormatSchema = z.stringFormat(
356
  "custom",
357
  /^[A-Z]{3}-\d{3}$/,
358
  "Invalid format"
359
);
360

361
// Custom format with function
362
const AsyncValidatorSchema = z.stringFormat(
363
  "available-username",
364
  async (username) => {
365
    const available = await checkUsernameAvailability(username);
366
    return available;
367
  },
368
  "Username already taken"
369
);
370
```
371

372
## Common Patterns
373

374
```typescript
375
// User validation
376
const UserSchema = z.object({
377
  email: z.email().max(255),
378
  website: z.url().optional(),
379
  phone: z.e164().optional(),
380
});
381

382
// API validation
383
const APIKeySchema = z.object({
384
  key: z.uuid(),
385
  secret: z.base64(),
386
});
387

388
// Network validation
389
const ServerSchema = z.object({
390
  host: z.hostname(),
391
  ip: z.ipv4(),
392
  subnet: z.cidrv4().optional(),
393
});
394

395
// ID validation
396
const ResourceSchema = z.object({
397
  id: z.ulid(),
398
  userId: z.cuid2(),
399
  sessionId: z.nanoid(),
400
});
401
```
402