0
# Primitive Schemas
1

2
Basic JavaScript type validators: strings, numbers, booleans, dates, and special types.
3

4
## String Schema
5

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

14
interface ZodString extends ZodType<string, string> {
15
  // Length constraints
16
  /**
17
   * Enforce minimum string length
18
   * @param length - Minimum number of characters
19
   * @param msg - Custom error message or options
20
   */
21
  min(length: number, msg?: string | { message?: string }): this;
22

23
  /**
24
   * Enforce maximum string length
25
   * @param length - Maximum number of characters
26
   * @param msg - Custom error message or options
27
   */
28
  max(length: number, msg?: string | { message?: string }): this;
29

30
  /**
31
   * Enforce exact string length
32
   * @param length - Exact number of characters required
33
   * @param msg - Custom error message or options
34
   */
35
  length(length: number, msg?: string | { message?: string }): this;
36

37
  /**
38
   * Require non-empty string (length > 0)
39
   * @param msg - Custom error message or options
40
   */
41
  nonempty(msg?: string | { message?: string }): this;
42

43
  // Pattern matching
44
  /**
45
   * Match string against regular expression
46
   * @param pattern - RegExp pattern to match
47
   * @param msg - Custom error message or options
48
   */
49
  regex(pattern: RegExp, msg?: string | { message?: string }): this;
50

51
  /** Require string to include substring */
52
  includes(substring: string, params?: { message?: string; position?: number }): this;
53

54
  /** Require string to start with prefix */
55
  startsWith(prefix: string, msg?: string | { message?: string }): this;
56

57
  /** Require string to end with suffix */
58
  endsWith(suffix: string, msg?: string | { message?: string }): this;
59

60
  // Case validation
61
  /** Validate string is all lowercase */
62
  lowercase(msg?: string | { message?: string }): this;
63

64
  /** Validate string is all uppercase */
65
  uppercase(msg?: string | { message?: string }): this;
66

67
  // Transformations
68
  /** Remove leading and trailing whitespace */
69
  trim(): this;
70

71
  /** Transform string to lowercase */
72
  toLowerCase(): this;
73

74
  /** Transform string to uppercase */
75
  toUpperCase(): this;
76

77
  /**
78
   * Normalize string using Unicode normalization
79
   * @param form - Unicode normalization form
80
   */
81
  normalize(form?: "NFC" | "NFD" | "NFKC" | "NFKD"): this;
82

83
  // Format validation (deprecated - use z.email(), z.url() instead)
84
  email(msg?: string | { message?: string }): this;
85
  url(msg?: string | { message?: string }): this;
86
  uuid(msg?: string | { message?: string }): this;
87
  guid(msg?: string | { message?: string }): this;
88
  jwt(msg?: string | { message?: string }): this;
89
  emoji(msg?: string | { message?: string }): this;
90
}
91
```
92

93
**Examples:**
94
```typescript
95
// Basic string
96
const NameSchema = z.string();
97

98
// Length constraints
99
const UsernameSchema = z.string().min(3).max(20);
100

101
// Pattern matching
102
const SlugSchema = z.string().regex(/^[a-zA-Z0-9_]+$/);
103

104
// Transformations
105
const TrimmedSchema = z.string().trim().toLowerCase();
106

107
// Non-empty
108
const RequiredSchema = z.string().nonempty();
109

110
// Complex validation
111
const CodeSchema = z.string().startsWith("CODE-").length(10);
112

113
// Case validation
114
const UppercaseSchema = z.string().uppercase();
115
```
116

117
## Number Schema
118

119
```typescript { .api }
120
/**
121
 * Create a number validation schema
122
 * @param params - Optional configuration with description and error map
123
 * @returns ZodNumber schema instance
124
 */
125
function number(params?: { description?: string; errorMap?: ZodErrorMap }): ZodNumber;
126

127
interface ZodNumber extends ZodType<number, number> {
128
  // Comparison constraints
129
  /**
130
   * Enforce minimum value
131
   * @param value - Minimum allowed value
132
   * @param params - Custom message and inclusive flag (default: true)
133
   */
134
  min(value: number, params?: string | { message?: string; inclusive?: boolean }): this;
135

136
  /**
137
   * Enforce maximum value
138
   * @param value - Maximum allowed value
139
   * @param params - Custom message and inclusive flag (default: true)
140
   */
141
  max(value: number, params?: string | { message?: string; inclusive?: boolean }): this;
142

143
  /** Require number less than value (exclusive) */
144
  lt(value: number, msg?: string | { message?: string }): this;
145

146
  /** Require number less than or equal to value */
147
  lte(value: number, msg?: string | { message?: string }): this;
148

149
  /** Require number greater than value (exclusive) */
150
  gt(value: number, msg?: string | { message?: string }): this;
151

152
  /** Require number greater than or equal to value */
153
  gte(value: number, msg?: string | { message?: string }): this;
154

155
  // Sign constraints
156
  /** Require positive number (> 0) */
157
  positive(msg?: string | { message?: string }): this;
158

159
  /** Require negative number (< 0) */
160
  negative(msg?: string | { message?: string }): this;
161

162
  /** Require non-negative number (>= 0) */
163
  nonnegative(msg?: string | { message?: string }): this;
164

165
  /** Require non-positive number (<= 0) */
166
  nonpositive(msg?: string | { message?: string }): this;
167

168
  // Type constraints
169
  /**
170
   * Require integer (no decimal places)
171
   * @param msg - Custom error message or options
172
   */
173
  int(msg?: string | { message?: string }): this;
174

175
  // Other constraints
176
  /**
177
   * Require number to be multiple of given value
178
   * @param value - Divisor that must divide evenly
179
   * @param msg - Custom error message or options
180
   */
181
  multipleOf(value: number, msg?: string | { message?: string }): this;
182

183
  /**
184
   * Require finite number (not Infinity or -Infinity)
185
   * @param msg - Custom error message or options
186
   */
187
  finite(msg?: string | { message?: string }): this;
188

189
  /**
190
   * Require safe integer (within Number.MIN_SAFE_INTEGER and Number.MAX_SAFE_INTEGER)
191
   * @param msg - Custom error message or options
192
   */
193
  safe(msg?: string | { message?: string }): this;
194
}
195
```
196

197
**Examples:**
198
```typescript
199
// Basic number
200
const AgeSchema = z.number();
201

202
// Range constraints
203
const PercentageSchema = z.number().min(0).max(100);
204

205
// Positive integer
206
const CountSchema = z.number().int().positive();
207

208
// Safe integer in range
209
const IDSchema = z.number().int().safe().positive();
210

211
// Multiple of constraint
212
const EvenSchema = z.number().multipleOf(2);
213

214
// Comparison operators
215
const ScoreSchema = z.number().gte(0).lt(100);
216
```
217

218
## Boolean Schema
219

220
```typescript { .api }
221
/**
222
 * Create a boolean validation schema
223
 * @param params - Optional configuration with description and error map
224
 * @returns ZodBoolean schema instance
225
 */
226
function boolean(params?: { description?: string; errorMap?: ZodErrorMap }): ZodBoolean;
227

228
interface ZodBoolean extends ZodType<boolean, boolean> {}
229
```
230

231
**Examples:**
232
```typescript
233
const IsActiveSchema = z.boolean();
234

235
const UserSchema = z.object({
236
  name: z.string(),
237
  isAdmin: z.boolean(),
238
  emailVerified: z.boolean(),
239
});
240
```
241

242
## BigInt Schema
243

244
```typescript { .api }
245
/**
246
 * Create a bigint validation schema for large integers
247
 * @param params - Optional configuration with description and error map
248
 * @returns ZodBigInt schema instance
249
 */
250
function bigint(params?: { description?: string; errorMap?: ZodErrorMap }): ZodBigInt;
251

252
interface ZodBigInt extends ZodType<bigint, bigint> {
253
  // Comparison constraints
254
  min(value: bigint, params?: string | { message?: string; inclusive?: boolean }): this;
255
  max(value: bigint, params?: string | { message?: string; inclusive?: boolean }): this;
256
  lt(value: bigint, msg?: string | { message?: string }): this;
257
  lte(value: bigint, msg?: string | { message?: string }): this;
258
  gt(value: bigint, msg?: string | { message?: string }): this;
259
  gte(value: bigint, msg?: string | { message?: string }): this;
260

261
  // Sign constraints
262
  positive(msg?: string | { message?: string }): this;
263
  negative(msg?: string | { message?: string }): this;
264
  nonnegative(msg?: string | { message?: string }): this;
265
  nonpositive(msg?: string | { message?: string }): this;
266

267
  // Multiple of constraint
268
  multipleOf(value: bigint, msg?: string | { message?: string }): this;
269
}
270
```
271

272
**Examples:**
273
```typescript
274
const LargeNumberSchema = z.bigint();
275

276
const PositiveBigIntSchema = z.bigint().positive();
277

278
const RangeBigIntSchema = z.bigint().min(0n).max(1000000000n);
279
```
280

281
## Date Schema
282

283
```typescript { .api }
284
/**
285
 * Create a Date object validation schema
286
 * @param params - Optional configuration with description and error map
287
 * @returns ZodDate schema instance
288
 */
289
function date(params?: { description?: string; errorMap?: ZodErrorMap }): ZodDate;
290

291
interface ZodDate extends ZodType<Date, Date> {
292
  min(date: Date, msg?: string | { message?: string }): this;
293
  max(date: Date, msg?: string | { message?: string }): this;
294
}
295
```
296

297
**Examples:**
298
```typescript
299
const BirthdateSchema = z.date();
300

301
const FutureDateSchema = z.date().min(new Date());
302

303
const DateRangeSchema = z.date()
304
  .min(new Date("2020-01-01"))
305
  .max(new Date("2025-12-31"));
306
```
307

308
## Special Type Schemas
309

310
```typescript { .api }
311
/**
312
 * Create an undefined validation schema
313
 * @returns ZodUndefined schema that only accepts undefined
314
 */
315
function undefined(): ZodUndefined;
316

317
/**
318
 * Create a null validation schema
319
 * @returns ZodNull schema that only accepts null
320
 */
321
function null(): ZodNull;
322

323
/**
324
 * Create an any schema (accepts any value without validation)
325
 * @returns ZodAny schema
326
 */
327
function any(): ZodAny;
328

329
/**
330
 * Create an unknown schema (accepts any value but requires type narrowing)
331
 * @returns ZodUnknown schema
332
 */
333
function unknown(): ZodUnknown;
334

335
/**
336
 * Create a never schema (rejects all values)
337
 * @param params - Optional configuration with description and error map
338
 * @returns ZodNever schema
339
 */
340
function never(params?: { description?: string; errorMap?: ZodErrorMap }): ZodNever;
341

342
/**
343
 * Create a void schema (accepts only undefined)
344
 * @returns ZodVoid schema
345
 */
346
function void(): ZodVoid;
347

348
/**
349
 * Create a NaN schema (accepts only NaN)
350
 * @param params - Optional configuration with description and error map
351
 * @returns ZodNaN schema
352
 */
353
function nan(params?: { description?: string; errorMap?: ZodErrorMap }): ZodNaN;
354

355
/**
356
 * Create a symbol validation schema
357
 * @param params - Optional configuration with description and error map
358
 * @returns ZodSymbol schema instance
359
 */
360
function symbol(params?: { description?: string; errorMap?: ZodErrorMap }): ZodSymbol;
361

362
interface ZodUndefined extends ZodType<undefined, undefined> {}
363
interface ZodNull extends ZodType<null, null> {}
364
interface ZodAny extends ZodType<any, any> {}
365
interface ZodUnknown extends ZodType<unknown, unknown> {}
366
interface ZodNever extends ZodType<never, never> {}
367
interface ZodVoid extends ZodType<void, undefined> {}
368
interface ZodNaN extends ZodType<number, number> {}
369
interface ZodSymbol extends ZodType<symbol, symbol> {}
370
```
371

372
**Examples:**
373
```typescript
374
// Symbol
375
const SymbolSchema = z.symbol();
376

377
// Undefined type
378
const UndefinedSchema = z.undefined();
379

380
// Null type
381
const NullSchema = z.null();
382

383
// Any (no validation)
384
const AnySchema = z.any();
385

386
// Unknown (validation required later)
387
const UnknownSchema = z.unknown();
388

389
// Never (always fails)
390
const NeverSchema = z.never();
391

392
// Void (undefined)
393
const VoidSchema = z.void();
394

395
// NaN check
396
const NaNSchema = z.nan();
397

398
// Symbol
399
const SymbolSchema = z.symbol();
400

401
// Nullable/optional patterns
402
const NullableStringSchema = z.union([z.string(), z.null()]);
403
// Or use built-in:
404
const NullableString2 = z.string().nullable();
405
const OptionalString = z.string().optional();
406
```
407

408
## Type Interfaces
409

410
Complete interface definitions with internal properties:
411

412
```typescript { .api }
413
interface ZodString extends ZodType<string, string> {
414
  minLength: number | null;
415
  maxLength: number | null;
416
  format: string | null;
417
}
418

419
interface ZodNumber extends ZodType<number, number> {}
420
interface ZodBoolean extends ZodType<boolean, boolean> {}
421
interface ZodBigInt extends ZodType<bigint, bigint> {}
422
interface ZodDate extends ZodType<Date, Date> {}
423
interface ZodSymbol extends ZodType<symbol, symbol> {}
424
interface ZodUndefined extends ZodType<undefined, undefined> {}
425
interface ZodNull extends ZodType<null, null> {}
426
interface ZodAny extends ZodType<any, any> {}
427
interface ZodUnknown extends ZodType<unknown, unknown> {}
428
interface ZodNever extends ZodType<never, never> {}
429
interface ZodVoid extends ZodType<void, undefined> {}
430
interface ZodNaN extends ZodType<number, number> {}
431
```
432