0
# Schema Types
1

2
Schema types are the core building blocks of yup validation. Each schema type provides specific validation methods tailored to its data type, while inheriting common functionality from the base Schema class.
3

4
## Capabilities
5

6
### Schema Factory Functions
7

8
Functions that create new schema instances for different data types.
9

10
```typescript { .api }
11
/**
12
 * Creates a schema for validating any type of value
13
 * @param spec - Optional mixed schema configuration
14
 * @returns MixedSchema instance
15
 */
16
function mixed<T = any>(spec?: MixedOptions): MixedSchema<T>;
17

18
/**
19
 * Creates a schema for validating string values
20
 * @returns StringSchema instance
21
 */
22
function string(): StringSchema;
23

24
/**
25
 * Creates a schema for validating number values  
26
 * @returns NumberSchema instance
27
 */
28
function number(): NumberSchema;
29

30
/**
31
 * Creates a schema for validating boolean values
32
 * @returns BooleanSchema instance
33
 */
34
function boolean(): BooleanSchema;
35

36
/**
37
 * Alias for boolean() function
38
 * @returns BooleanSchema instance
39
 */
40
function bool(): BooleanSchema;
41

42
/**
43
 * Creates a schema for validating Date objects
44
 * @returns DateSchema instance
45
 */
46
function date(): DateSchema;
47

48
/**
49
 * Creates a schema for validating object structures
50
 * @param shape - Object shape definition with field schemas
51
 * @returns ObjectSchema instance
52
 */
53
function object<T extends ObjectShape = {}>(shape?: T): ObjectSchema<T>;
54

55
/**
56
 * Creates a schema for validating arrays
57
 * @param innerType - Schema for validating array elements
58
 * @returns ArraySchema instance
59
 */
60
function array<T = any>(innerType?: Schema<T>): ArraySchema<T>;
61

62
/**
63
 * Creates a schema for validating tuples with fixed element types
64
 * @param types - Array of schemas for each tuple position
65
 * @returns TupleSchema instance
66
 */
67
function tuple<T extends readonly [...any[]]>(types: T): TupleSchema<T>;
68

69
interface MixedOptions {
70
  type?: string;
71
  check?: (value: any) => boolean;
72
}
73

74
type ObjectShape = Record<string, Schema>;
75
```
76

77
### Base Schema Methods
78

79
All schema types inherit these core methods from the base Schema class.
80

81
```typescript { .api }
82
/**
83
 * Create a copy of the schema with optional modifications
84
 * @param spec - Modifications to apply to the cloned schema
85
 * @returns New schema instance
86
 */
87
clone(spec?: Partial<SchemaSpec>): this;
88

89
/**
90
 * Merge this schema with another schema
91
 * @param schema - Schema to merge with
92
 * @returns New merged schema
93
 */
94
concat(schema: Schema): Schema;
95

96
/**
97
 * Set a default value for the schema
98
 * @param value - Default value or factory function
99
 * @returns New schema with default value
100
 */
101
default<D>(value: D | (() => D)): Schema;
102

103
/**
104
 * Enable or disable strict validation mode
105
 * @param isStrict - Whether to enable strict mode
106
 * @returns New schema with strict mode setting
107
 */
108
strict(isStrict?: boolean): this;
109

110
/**
111
 * Enable or disable field stripping in parent objects
112
 * @param enabled - Whether to strip this field
113
 * @returns New schema with strip setting
114
 */
115
strip(enabled?: boolean): this;
116
```
117

118
### Optionality & Nullability
119

120
Methods for controlling whether values are required and handling null/undefined values.
121

122
```typescript { .api }
123
/**
124
 * Mark the schema as required (no undefined values allowed)
125
 * @param message - Custom error message
126
 * @returns New required schema
127
 */
128
required(message?: string): Schema;
129

130
/**
131
 * Mark the schema as optional (undefined values allowed)
132
 * @returns New optional schema
133
 */
134
notRequired(): Schema;
135

136
/**
137
 * Mark the schema as optional (alias for notRequired)
138
 * @returns New optional schema
139
 */
140
optional(): Schema;
141

142
/**
143
 * Require the value to be defined (no undefined values)
144
 * @param message - Custom error message
145
 * @returns New schema that rejects undefined
146
 */
147
defined(message?: string): Schema;
148

149
/**
150
 * Allow null values
151
 * @param message - Custom error message for type conversion
152
 * @returns New schema that accepts null
153
 */
154
nullable(message?: string): Schema;
155

156
/**
157
 * Disallow null values
158
 * @param message - Custom error message
159
 * @returns New schema that rejects null
160
 */
161
nonNullable(message?: string): Schema;
162
```
163

164
### Value Constraints
165

166
Methods for constraining valid values using whitelists and blacklists.
167

168
```typescript { .api }
169
/**
170
 * Allow only specific values (whitelist)
171
 * @param arrayOfValues - Array of allowed values
172
 * @param message - Custom error message
173
 * @returns New schema with value constraint
174
 */
175
oneOf<U extends T>(arrayOfValues: ReadonlyArray<U>, message?: string): Schema<U>;
176

177
/**
178
 * Disallow specific values (blacklist)
179
 * @param arrayOfValues - Array of disallowed values
180
 * @param message - Custom error message
181
 * @returns New schema with value constraint
182
 */
183
notOneOf(arrayOfValues: ReadonlyArray<T>, message?: string): Schema;
184

185
// Aliases for oneOf
186
equals<U extends T>(arrayOfValues: ReadonlyArray<U>, message?: string): Schema<U>;
187
is<U extends T>(arrayOfValues: ReadonlyArray<U>, message?: string): Schema<U>;
188

189
// Aliases for notOneOf
190
not(arrayOfValues: ReadonlyArray<T>, message?: string): Schema;
191
nope(arrayOfValues: ReadonlyArray<T>, message?: string): Schema;
192
```
193

194
## String Schema
195

196
Specialized schema for string validation with string-specific methods.
197

198
```typescript { .api }
199
/**
200
 * Validate exact string length
201
 * @param length - Required string length
202
 * @param message - Custom error message
203
 * @returns New schema with length constraint
204
 */
205
length(length: number, message?: string): StringSchema;
206

207
/**
208
 * Validate minimum string length
209
 * @param min - Minimum allowed length
210
 * @param message - Custom error message
211
 * @returns New schema with minimum length constraint
212
 */
213
min(min: number, message?: string): StringSchema;
214

215
/**
216
 * Validate maximum string length
217
 * @param max - Maximum allowed length
218
 * @param message - Custom error message
219
 * @returns New schema with maximum length constraint
220
 */
221
max(max: number, message?: string): StringSchema;
222

223
/**
224
 * Validate string against regular expression pattern
225
 * @param regex - Regular expression to match
226
 * @param options - Match options or custom error message
227
 * @returns New schema with regex constraint
228
 */
229
matches(regex: RegExp, options?: string | MatchOptions): StringSchema;
230

231
/**
232
 * Validate email format
233
 * @param message - Custom error message
234
 * @returns New schema with email validation
235
 */
236
email(message?: string): StringSchema;
237

238
/**
239
 * Validate URL format
240
 * @param message - Custom error message
241
 * @returns New schema with URL validation
242
 */
243
url(message?: string): StringSchema;
244

245
/**
246
 * Validate UUID format
247
 * @param message - Custom error message
248
 * @returns New schema with UUID validation
249
 */
250
uuid(message?: string): StringSchema;
251

252
/**
253
 * Validate ISO datetime format
254
 * @param options - Datetime validation options
255
 * @returns New schema with datetime validation
256
 */
257
datetime(options?: DateTimeOptions): StringSchema;
258

259
/**
260
 * Trim whitespace and validate the result
261
 * @param message - Custom error message for transformation
262
 * @returns New schema with trim transformation
263
 */
264
trim(message?: string): StringSchema;
265

266
/**
267
 * Convert to lowercase and validate the result
268
 * @param message - Custom error message for transformation
269
 * @returns New schema with lowercase transformation
270
 */
271
lowercase(message?: string): StringSchema;
272

273
/**
274
 * Convert to uppercase and validate the result
275
 * @param message - Custom error message for transformation
276
 * @returns New schema with uppercase transformation
277
 */
278
uppercase(message?: string): StringSchema;
279

280
/**
281
 * Override for string schemas: require non-empty strings
282
 * For strings, required() validates that the string has a length > 0
283
 * @param message - Custom error message
284
 * @returns New required schema that rejects empty strings
285
 */
286
required(message?: string): StringSchema;
287

288
/**
289
 * Override for string schemas: remove the non-empty string requirement
290
 * @returns New optional schema that allows empty strings
291
 */
292
notRequired(): StringSchema;
293

294
/**
295
 * Ensure string is not null (converts null to empty string)
296
 * @returns New schema with null handling
297
 */
298
ensure(): StringSchema;
299

300
interface MatchOptions {
301
  message?: string;
302
  excludeEmptyString?: boolean;
303
}
304

305
interface DateTimeOptions {
306
  precision?: number;
307
  offset?: boolean;
308
  message?: string;
309
}
310
```
311

312
## Number Schema
313

314
Specialized schema for number validation with numeric constraints.
315

316
```typescript { .api }
317
/**
318
 * Validate minimum numeric value
319
 * @param min - Minimum allowed value
320
 * @param message - Custom error message
321
 * @returns New schema with minimum constraint
322
 */
323
min(min: number, message?: string): NumberSchema;
324

325
/**
326
 * Validate maximum numeric value
327
 * @param max - Maximum allowed value
328
 * @param message - Custom error message
329
 * @returns New schema with maximum constraint
330
 */
331
max(max: number, message?: string): NumberSchema;
332

333
/**
334
 * Validate value is strictly less than specified number
335
 * @param less - Upper bound (exclusive)
336
 * @param message - Custom error message
337
 * @returns New schema with less-than constraint
338
 */
339
lessThan(less: number, message?: string): NumberSchema;
340

341
/**
342
 * Validate value is strictly greater than specified number
343
 * @param more - Lower bound (exclusive)
344
 * @param message - Custom error message
345
 * @returns New schema with greater-than constraint
346
 */
347
moreThan(more: number, message?: string): NumberSchema;
348

349
/**
350
 * Validate value is positive (> 0)
351
 * @param message - Custom error message
352
 * @returns New schema with positive constraint
353
 */
354
positive(message?: string): NumberSchema;
355

356
/**
357
 * Validate value is negative (< 0)
358
 * @param message - Custom error message
359
 * @returns New schema with negative constraint
360
 */
361
negative(message?: string): NumberSchema;
362

363
/**
364
 * Validate value is an integer
365
 * @param message - Custom error message
366
 * @returns New schema with integer constraint
367
 */
368
integer(message?: string): NumberSchema;
369

370
/**
371
 * Truncate number to integer
372
 * @returns New schema with truncation transformation
373
 */
374
truncate(): NumberSchema;
375

376
/**
377
 * Round number using specified method
378
 * @param method - Rounding method ("ceil", "floor", "round", "trunc")
379
 * @returns New schema with rounding transformation
380
 */
381
round(method?: "ceil" | "floor" | "round" | "trunc"): NumberSchema;
382
```
383

384
## Boolean Schema
385

386
Specialized schema for boolean validation.
387

388
```typescript { .api }
389
/**
390
 * Validate value must be true
391
 * @param message - Custom error message
392
 * @returns New schema requiring true value
393
 */
394
isTrue(message?: string): BooleanSchema;
395

396
/**
397
 * Validate value must be false
398
 * @param message - Custom error message
399
 * @returns New schema requiring false value
400
 */
401
isFalse(message?: string): BooleanSchema;
402
```
403

404
## Date Schema
405

406
Specialized schema for Date validation with date-specific constraints.
407

408
```typescript { .api }
409
/**
410
 * Validate minimum date value
411
 * @param min - Minimum allowed date
412
 * @param message - Custom error message
413
 * @returns New schema with minimum date constraint
414
 */
415
min(min: Date | string | Reference, message?: string): DateSchema;
416

417
/**
418
 * Validate maximum date value
419
 * @param max - Maximum allowed date
420
 * @param message - Custom error message
421
 * @returns New schema with maximum date constraint
422
 */
423
max(max: Date | string | Reference, message?: string): DateSchema;
424

425
/**
426
 * Static property representing an invalid Date
427
 */
428
static INVALID_DATE: Date;
429
```
430

431
## Object Schema
432

433
Specialized schema for object validation with structure definition and manipulation.
434

435
```typescript { .api }
436
/**
437
 * Define or modify object shape
438
 * @param additions - Field schemas to add
439
 * @param excludes - Field names to exclude
440
 * @returns New schema with updated shape
441
 */
442
shape<U extends ObjectShape>(
443
  additions: U,
444
  excludes?: [string, string][]
445
): ObjectSchema<U>;
446

447
/**
448
 * Object containing field definitions
449
 */
450
fields: ObjectShape;
451

452
/**
453
 * Select only specified fields from object
454
 * @param keys - Field names to include
455
 * @returns New schema with selected fields only
456
 */
457
pick<K extends keyof T>(keys: K[]): ObjectSchema<Pick<T, K>>;
458

459
/**
460
 * Exclude specified fields from object
461
 * @param keys - Field names to exclude
462
 * @returns New schema without excluded fields
463
 */
464
omit<K extends keyof T>(keys: K[]): ObjectSchema<Omit<T, K>>;
465

466
/**
467
 * Make all fields optional
468
 * @returns New schema with all optional fields
469
 */
470
partial(): ObjectSchema<Partial<T>>;
471

472
/**
473
 * Make all fields recursively optional
474
 * @returns New schema with deeply optional fields
475
 */
476
deepPartial(): ObjectSchema<DeepPartial<T>>;
477

478
/**
479
 * Disallow unknown keys in object
480
 * @param allow - Whether to allow unknown keys
481
 * @param message - Custom error message
482
 * @returns New schema with unknown key handling
483
 */
484
noUnknown(allow?: boolean, message?: string): ObjectSchema;
485

486
/**
487
 * Configure unknown key handling
488
 * @param allow - Whether to allow unknown keys
489
 * @param message - Custom error message
490
 * @returns New schema with unknown key handling
491
 */
492
unknown(allow?: boolean, message?: string): ObjectSchema;
493

494
/**
495
 * Strip unknown keys from validated objects
496
 * @returns New schema that strips unknown keys
497
 */
498
stripUnknown(): ObjectSchema;
499

500
/**
501
 * Validate exact object shape without stripping
502
 * @param message - Custom error message
503
 * @returns New schema requiring exact shape
504
 */
505
exact(message?: string): ObjectSchema;
506

507
/**
508
 * Move or copy field values during validation
509
 * @param from - Source field name
510
 * @param to - Target field name  
511
 * @param alias - Whether to copy (true) or move (false)
512
 * @returns New schema with field transformation
513
 */
514
from(from: string, to: string, alias?: boolean): ObjectSchema;
515

516
/**
517
 * Parse JSON string to object during validation
518
 * @returns New schema with JSON parsing
519
 */
520
json(): ObjectSchema;
521

522
/**
523
 * Transform all object keys using provided function
524
 * @param fn - Key transformation function
525
 * @returns New schema with key transformation
526
 */
527
transformKeys(fn: (key: string) => string): ObjectSchema;
528

529
/**
530
 * Convert all keys to camelCase
531
 * @returns New schema with camelCase key transformation
532
 */
533
camelCase(): ObjectSchema;
534

535
/**
536
 * Convert all keys to snake_case
537
 * @returns New schema with snake_case key transformation
538
 */
539
snakeCase(): ObjectSchema;
540

541
/**
542
 * Convert all keys to CONSTANT_CASE
543
 * @returns New schema with CONSTANT_CASE key transformation
544
 */
545
constantCase(): ObjectSchema;
546

547
type DeepPartial<T> = {
548
  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
549
};
550
```
551

552
## Array Schema
553

554
Specialized schema for array validation with element type definition and array-specific constraints.
555

556
```typescript { .api }
557
/**
558
 * Define schema for array elements
559
 * @param schema - Schema to validate each array element
560
 * @returns New schema with element validation
561
 */
562
of<U>(schema: Schema<U>): ArraySchema<U>;
563

564
/**
565
 * Schema for validating array elements
566
 */
567
innerType: Schema | undefined;
568

569
/**
570
 * Validate exact array length
571
 * @param length - Required array length
572
 * @param message - Custom error message
573
 * @returns New schema with length constraint
574
 */
575
length(length: number, message?: string): ArraySchema;
576

577
/**
578
 * Validate minimum array length
579
 * @param min - Minimum allowed length
580
 * @param message - Custom error message
581
 * @returns New schema with minimum length constraint
582
 */
583
min(min: number, message?: string): ArraySchema;
584

585
/**
586
 * Validate maximum array length
587
 * @param max - Maximum allowed length
588
 * @param message - Custom error message
589
 * @returns New schema with maximum length constraint
590
 */
591
max(max: number, message?: string): ArraySchema;
592

593
/**
594
 * Ensure array exists (converts null to empty array)
595
 * @returns New schema with null handling
596
 */
597
ensure(): ArraySchema;
598

599
/**
600
 * Remove falsy or rejected values from array
601
 * @param rejector - Function to test which values to remove
602
 * @returns New schema with compaction transformation
603
 */
604
compact(rejector?: (value: T) => boolean): ArraySchema<NonNullable<T>>;
605

606
/**
607
 * Parse JSON string to array during validation
608
 * @returns New schema with JSON parsing
609
 */
610
json(): ArraySchema;
611
```
612

613
## Tuple Schema
614

615
Specialized schema for tuple validation with fixed element positions and types.
616

617
```typescript { .api }
618
/**
619
 * Array of schemas for each tuple position
620
 */
621
spec: {
622
  types: Schema[];
623
};
624
```
625

626
## Schema Classes
627

628
The actual schema class definitions that provide the implementation for all schema functionality.
629

630
```typescript { .api }
631
/**
632
 * Base schema class - all other schemas extend this
633
 */
634
abstract class Schema<T = any, C = any, F = any, D = any> {
635
  // Core validation and casting methods inherited by all schemas
636
  cast(value: any, options?: CastOptions<C>): T;
637
  validate(value: any, options?: ValidateOptions<C>): Promise<T>;
638
  validateSync(value: any, options?: ValidateOptions<C>): T;
639
  isValid(value: any, options?: ValidateOptions<C>): Promise<boolean>;
640
  isValidSync(value: any, options?: ValidateOptions<C>): boolean;
641
  isType(value: any): value is T;
642
}
643

644
/**
645
 * Schema for validating any type of value
646
 */
647
class MixedSchema<T = any> extends Schema<T> {}
648

649
/**
650
 * Schema for validating string values
651
 */
652
class StringSchema extends Schema<string> {}
653

654
/**
655
 * Schema for validating number values
656
 */
657
class NumberSchema extends Schema<number> {}
658

659
/**
660
 * Schema for validating boolean values
661
 */
662
class BooleanSchema extends Schema<boolean> {}
663

664
/**
665
 * Schema for validating Date objects
666
 */
667
class DateSchema extends Schema<Date> {}
668

669
/**
670
 * Schema for validating object structures
671
 */
672
class ObjectSchema<T extends ObjectShape = {}> extends Schema<T> {}
673

674
/**
675
 * Schema for validating arrays
676
 */
677
class ArraySchema<T = any> extends Schema<T[]> {}
678

679
/**
680
 * Schema for validating tuples with fixed element types
681
 */
682
class TupleSchema<T extends readonly [...any[]]> extends Schema<T> {}
683
```