0
# Schema Types
1

2
Joi provides comprehensive schema types for validating different data types with extensive configuration options and validation rules.
3

4
## Capabilities
5

6
### Any Schema
7

8
Base schema type that matches any data type and provides fundamental validation methods.
9

10
```typescript { .api }
11
/**
12
 * Creates a schema that matches any data type
13
 * @returns AnySchema instance with base validation methods
14
 */
15
function any(): AnySchema;
16

17
interface AnySchema<T = any> {
18
  // Value constraints
19
  allow(...values: any[]): this;
20
  disallow(...values: any[]): this;
21
  valid(...values: any[]): this;
22
  invalid(...values: any[]): this;
23
  equal(...values: any[]): this;
24
  only(...values: any[]): this;
25
  
26
  // Presence modifiers
27
  required(): this;
28
  optional(): this;
29
  forbidden(): this;
30
  exist(): this;
31
  
32
  // Default and failover values
33
  default(value?: any | Reference | ((parent: any, helpers: CustomHelpers) => any), description?: string): this;
34
  failover(value?: any | Reference | ((parent: any, helpers: CustomHelpers) => any), description?: string): this;
35
  empty(schema?: SchemaLike): this;
36
  
37
  // Conditional validation
38
  when(condition: string | Reference | Schema, options: WhenOptions): this;
39
  when(condition: Schema, options: WhenSchemaOptions): this;
40
  
41
  // Custom validation
42
  custom(method: CustomValidator, description?: string): this;
43
  external(method: ExternalValidator, description?: string): this;
44
  
45
  // Metadata and documentation
46
  description(desc: string): this;
47
  example(value: any, options?: ExampleOptions): this;
48
  meta(meta: any): this;
49
  note(note: string): this;
50
  tag(...tags: string[]): this;
51
  label(name: string): this;
52
  id(id?: string): this;
53
  
54
  // Schema manipulation
55
  concat(schema: this): this;
56
  fork(paths: string | string[], adjuster: (schema: Schema) => Schema): this;
57
  extract(paths: string | string[]): Schema;
58
  unknown(allow?: boolean): this;
59
  
60
  // Validation execution
61
  validate(value: any, options?: ValidationOptions): ValidationResult<T>;
62
  validateAsync(value: any, options?: ValidationOptions): Promise<T>;
63
  attempt(value: any, options?: ValidationOptions): T;
64
  assert(value: any, options?: ValidationOptions): T;
65
  
66
  // Introspection
67
  describe(): SchemaDescription;
68
  type: string;
69
  $: this;
70
  
71
  // Configuration
72
  prefs(preferences: ValidationOptions): this;
73
  preferences(preferences: ValidationOptions): this;
74
  options(options: ValidationOptions): this;
75
  strict(isStrict?: boolean): this;
76
  
77
  // Rules and messages
78
  rule(options: RuleOptions): this;
79
  message(message: string | LanguageMessages): this;
80
  error(err: Error | string | ((errors: ErrorReport[]) => Error | string)): this;
81
  warn(): this;
82
  
83
  // Caching and performance
84
  cache(cache?: boolean): this;
85
  
86
  // Schema chaining
87
  keep(): this;
88
  strip(): this;
89
}
90
```
91

92
### String Schema
93

94
Schema for validating string values with format validation, length constraints, and pattern matching.
95

96
```typescript { .api }
97
/**
98
 * Creates a string validation schema
99
 * @returns StringSchema with string-specific validation methods
100
 */
101
function string(): StringSchema;
102

103
interface StringSchema extends AnySchema<string> {
104
  // Length validation
105
  length(limit: number | Reference): this;
106
  min(limit: number | Reference): this;
107
  max(limit: number | Reference): this;
108
  
109
  // Pattern matching
110
  pattern(regex: RegExp, options?: PatternOptions): this;
111
  regex(regex: RegExp, options?: PatternOptions): this;
112
  replace(pattern: RegExp | string, replacement: string): this;
113
  
114
  // Character set validation
115
  alphanum(): this;
116
  token(): this;
117
  hex(options?: HexOptions): this;
118
  base64(options?: Base64Options): this;
119
  
120
  // Format validation
121
  creditCard(): this;
122
  dataUri(options?: DataUriOptions): this;
123
  domain(options?: DomainOptions): this;
124
  email(options?: EmailOptions): this;
125
  guid(options?: GuidOptions): this;
126
  uuid(options?: UuidOptions): this;
127
  hostname(): this;
128
  ip(options?: IpOptions): this;
129
  uri(options?: UriOptions): this;
130
  isoDate(): this;
131
  isoDuration(): this;
132
  
133
  // Case operations
134
  lowercase(): this;
135
  uppercase(): this;
136
  case(direction: 'upper' | 'lower'): this;
137
  
138
  // String manipulation
139
  trim(enabled?: boolean): this;
140
  truncate(enabled?: boolean): this;
141
  normalize(form?: 'NFC' | 'NFD' | 'NFKC' | 'NFKD'): this;
142
}
143

144
interface EmailOptions {
145
  allowUnicode?: boolean;
146
  ignoreLength?: boolean;
147
  minDomainSegments?: number;
148
  multiple?: boolean;
149
  separator?: string | string[];
150
  tlds?: boolean | { allow?: Set<string> | string[] | boolean; deny?: Set<string> | string[] };
151
}
152

153
interface UriOptions {
154
  allowRelative?: boolean;
155
  allowQuerySquareBrackets?: boolean;
156
  domain?: DomainOptions;
157
  relativeOnly?: boolean;
158
  scheme?: string | RegExp | Array<string | RegExp>;
159
}
160
```
161

162
### Number Schema
163

164
Schema for validating numeric values with range constraints and precision control.
165

166
```typescript { .api }
167
/**
168
 * Creates a number validation schema
169
 * @returns NumberSchema with number-specific validation methods
170
 */
171
function number(): NumberSchema;
172

173
interface NumberSchema extends AnySchema<number> {
174
  // Range validation
175
  min(limit: number | Reference): this;
176
  max(limit: number | Reference): this;
177
  greater(limit: number | Reference): this;
178
  less(limit: number | Reference): this;
179
  
180
  // Sign validation
181
  positive(): this;
182
  negative(): this;
183
  sign(sign: 'positive' | 'negative'): this;
184
  
185
  // Type constraints
186
  integer(): this;
187
  precision(limit: number): this;
188
  multiple(base: number | Reference): this;
189
  port(): this;
190
  unsafe(enabled?: boolean): this;
191
}
192
```
193

194
### Boolean Schema
195

196
Schema for validating boolean values with truthy/falsy value conversion.
197

198
```typescript { .api }
199
/**
200
 * Creates a boolean validation schema
201
 * @returns BooleanSchema with boolean-specific validation methods
202
 */
203
function boolean(): BooleanSchema;
204

205
interface BooleanSchema extends AnySchema<boolean> {
206
  // Conversion options
207
  truthy(...values: any[]): this;
208
  falsy(...values: any[]): this;
209
  sensitive(enabled?: boolean): this;
210
}
211
```
212

213
### Array Schema
214

215
Schema for validating arrays with element validation and length constraints.
216

217
```typescript { .api }
218
/**
219
 * Creates an array validation schema
220
 * @returns ArraySchema with array-specific validation methods
221
 */
222
function array(): ArraySchema;
223

224
interface ArraySchema<T = any> extends AnySchema<T[]> {
225
  // Element validation
226
  items(...schemas: SchemaLike[]): this;
227
  ordered(...schemas: SchemaLike[]): this;
228
  has(schema: SchemaLike): this;
229
  
230
  // Length constraints
231
  length(limit: number | Reference): this;
232
  min(limit: number | Reference): this;
233
  max(limit: number | Reference): this;
234
  
235
  // Array properties
236
  sparse(enabled?: boolean): this;
237
  single(enabled?: boolean): this;
238
  unique(comparator?: string | ((a: any, b: any) => boolean), options?: UniqueOptions): this;
239
  sort(options?: SortOptions): this;
240
}
241

242
interface UniqueOptions {
243
  ignoreUndefined?: boolean;
244
}
245

246
interface SortOptions {
247
  order?: 'ascending' | 'descending';
248
  by?: string | Reference;
249
}
250
```
251

252
### Object Schema
253

254
Schema for validating objects with key validation and relationship constraints.
255

256
```typescript { .api }
257
/**
258
 * Creates an object validation schema
259
 * @param schema Optional object schema mapping
260
 * @returns ObjectSchema with object-specific validation methods
261
 */
262
function object(schema?: SchemaMap): ObjectSchema;
263

264
interface ObjectSchema<T = any> extends AnySchema<T> {
265
  // Key management
266
  keys(schema?: SchemaMap): this;
267
  append(schema: SchemaMap): this;
268
  unknown(allow?: boolean): this;
269
  
270
  // Key relationships
271
  and(...peers: string[]): this;
272
  nand(...peers: string[]): this;
273
  or(...peers: string[]): this;
274
  xor(...peers: string[]): this;
275
  oxor(...peers: string[]): this;
276
  with(key: string, peers: string | string[]): this;
277
  without(key: string, peers: string | string[]): this;
278
  
279
  // Key requirements
280
  requiredKeys(...keys: string[]): this;
281
  optionalKeys(...keys: string[]): this;
282
  forbiddenKeys(...keys: string[]): this;
283
  
284
  // Pattern matching
285
  pattern(pattern: RegExp | Schema, schema: SchemaLike, options?: PatternOptions): this;
286
  
287
  // Object validation
288
  length(limit: number): this;
289
  min(limit: number): this;
290
  max(limit: number): this;
291
  
292
  // Type constraints
293
  instance(constructor: Function, name?: string): this;
294
  schema(type?: SchemaLike): this;
295
  
296
  // Assertions
297
  assert(ref: string | Reference, schema: SchemaLike, message?: string): this;
298
}
299

300
type SchemaMap<T = any> = {
301
  [K in keyof T]?: SchemaLike<T[K]>;
302
};
303
```
304

305
### Date Schema
306

307
Schema for validating Date objects with timestamp and range validation.
308

309
```typescript { .api }
310
/**
311
 * Creates a date validation schema
312
 * @returns DateSchema with date-specific validation methods
313
 */
314
function date(): DateSchema;
315

316
interface DateSchema extends AnySchema<Date> {
317
  // Range validation
318
  greater(date: 'now' | Date | number | string | Reference): this;
319
  less(date: 'now' | Date | number | string | Reference): this;
320
  min(date: 'now' | Date | number | string | Reference): this;
321
  max(date: 'now' | Date | number | string | Reference): this;
322
  
323
  // Format validation
324
  iso(): this;
325
  timestamp(type?: 'javascript' | 'unix'): this;
326
}
327
```
328

329
### Function Schema
330

331
Schema for validating function objects with arity and class constraints.
332

333
```typescript { .api }
334
/**
335
 * Creates a function validation schema
336
 * @returns FunctionSchema with function-specific validation methods
337
 */
338
function function(): FunctionSchema;
339

340
interface FunctionSchema extends AnySchema<Function> {
341
  // Function properties
342
  arity(n: number): this;
343
  minArity(n: number): this;
344
  maxArity(n: number): this;
345
  class(): this;
346
}
347
```
348

349
### Binary Schema
350

351
Schema for validating Buffer objects with encoding and length constraints.
352

353
```typescript { .api }
354
/**
355
 * Creates a binary validation schema (conditionally available)
356
 * @returns BinarySchema with binary-specific validation methods
357
 */
358
function binary(): BinarySchema;
359

360
interface BinarySchema extends AnySchema<Buffer> {
361
  // Length constraints
362
  length(limit: number | Reference): this;
363
  min(limit: number | Reference): this;
364
  max(limit: number | Reference): this;
365
  
366
  // Encoding
367
  encoding(encoding: string): this;
368
}
369
```
370

371
### Symbol Schema
372

373
Schema for validating Symbol values with mapping support.
374

375
```typescript { .api }
376
/**
377
 * Creates a symbol validation schema
378
 * @returns SymbolSchema with symbol-specific validation methods
379
 */
380
function symbol(): SymbolSchema;
381

382
interface SymbolSchema extends AnySchema<symbol> {
383
  // Value mapping
384
  map(iterable: Iterable<[any, symbol]> | { [key: string]: symbol }): this;
385
}
386
```
387

388
### Alternatives Schema
389

390
Schema for validating against multiple possible schema types.
391

392
```typescript { .api }
393
/**
394
 * Creates an alternatives validation schema
395
 * @param types Optional alternative schema types
396
 * @returns AlternativesSchema with alternatives-specific validation methods
397
 */
398
function alternatives(...types: SchemaLike[]): AlternativesSchema;
399

400
interface AlternativesSchema<T = any> extends AnySchema<T> {
401
  // Alternative matching
402
  try<A>(a: SchemaLike<A>): AlternativesSchema<A>;
403
  try<A, B>(a: SchemaLike<A>, b: SchemaLike<B>): AlternativesSchema<A | B>;
404
  try<A, B, C>(a: SchemaLike<A>, b: SchemaLike<B>, c: SchemaLike<C>): AlternativesSchema<A | B | C>;
405
  
406
  // Conditional logic
407
  conditional(ref: string | Reference, options: WhenOptions): this;
408
  conditional(ref: Schema, options: WhenSchemaOptions): this;
409
  
410
  // Matching mode
411
  match(mode: 'any' | 'all' | 'one'): this;
412
}
413
```
414

415
### Link Schema
416

417
Schema for creating references to other schemas, enabling recursive validation.
418

419
```typescript { .api }
420
/**
421
 * Creates a link validation schema for recursive structures
422
 * @param ref Optional reference to link to
423
 * @returns LinkSchema with link-specific validation methods
424
 */
425
function link(ref?: string): LinkSchema;
426

427
interface LinkSchema<T = any> extends AnySchema<T> {
428
  // Schema linking
429
  concat(schema: SchemaLike): this;
430
  link(ref?: string): this;
431
}
432
```
433

434
## Type Aliases
435

436
```typescript { .api }
437
// Convenience aliases for common schema types
438
const bool: typeof boolean;
439
const func: typeof function;
440
const alt: typeof alternatives;
441
```
442

443
## Usage Examples
444

445
**Basic String Validation:**
446

447
```javascript
448
const schema = Joi.string().min(3).max(50).required();
449
const { error, value } = schema.validate('hello');
450
```
451

452
**Object Validation with Nested Schemas:**
453

454
```javascript
455
const userSchema = Joi.object({
456
    name: Joi.string().required(),
457
    email: Joi.string().email().required(),
458
    age: Joi.number().integer().min(18),
459
    preferences: Joi.object({
460
        theme: Joi.string().valid('light', 'dark'),
461
        notifications: Joi.boolean()
462
    })
463
});
464
```
465

466
**Array Validation:**
467

468
```javascript
469
const listSchema = Joi.array()
470
    .items(Joi.string().min(1))
471
    .min(1)
472
    .max(10)
473
    .unique();
474
```
475

476
**Alternatives Schema:**
477

478
```javascript
479
const mixedSchema = Joi.alternatives().try(
480
    Joi.string(),
481
    Joi.number(),
482
    Joi.boolean()
483
);
484
```