0
# Basic Types
1

2
Core JSON Schema compatible types that form the foundation of all TypeBox schemas. These types provide primitive and structured data validation with full TypeScript inference.
3

4
## Capabilities
5

6
### String Type
7

8
Creates a string type with optional validation constraints.
9

10
```typescript { .api }
11
/**
12
 * Creates a string type with optional validation constraints
13
 * @param options - String validation options
14
 * @returns TString schema
15
 */
16
function String(options?: StringOptions): TString;
17

18
interface StringOptions extends SchemaOptions {
19
  minLength?: number;
20
  maxLength?: number;
21
  pattern?: string;
22
  format?: 'date-time' | 'date' | 'time' | 'email' | 'hostname' | 'ipv4' | 'ipv6' | 'uri' | 'uuid' | string;
23
}
24
```
25

26
**Usage Examples:**
27

28
```typescript
29
import { Type } from "@sinclair/typebox";
30

31
// Basic string
32
const Name = Type.String();
33

34
// String with length constraints
35
const Username = Type.String({ minLength: 3, maxLength: 20 });
36

37
// String with pattern validation
38
const PhoneNumber = Type.String({ pattern: '^\\+?[1-9]\\d{1,14}$' });
39

40
// String with format validation
41
const Email = Type.String({ format: 'email' });
42
const UUID = Type.String({ format: 'uuid' });
43
```
44

45
### Number Type
46

47
Creates a number type with optional validation constraints.
48

49
```typescript { .api }
50
/**
51
 * Creates a number type with optional validation constraints
52
 * @param options - Number validation options
53
 * @returns TNumber schema
54
 */
55
function Number(options?: NumberOptions): TNumber;
56

57
interface NumberOptions extends SchemaOptions {
58
  minimum?: number;
59
  maximum?: number;
60
  exclusiveMinimum?: number;
61
  exclusiveMaximum?: number;
62
  multipleOf?: number;
63
}
64
```
65

66
**Usage Examples:**
67

68
```typescript
69
// Basic number
70
const Age = Type.Number();
71

72
// Number with range constraints
73
const Score = Type.Number({ minimum: 0, maximum: 100 });
74

75
// Number with exclusive bounds
76
const Temperature = Type.Number({ exclusiveMinimum: -273.15 });
77

78
// Number with multiple constraint
79
const EvenNumber = Type.Number({ multipleOf: 2 });
80
```
81

82
### Integer Type
83

84
Creates an integer type with optional validation constraints.
85

86
```typescript { .api }
87
/**
88
 * Creates an integer type with optional validation constraints
89
 * @param options - Integer validation options
90
 * @returns TInteger schema
91
 */
92
function Integer(options?: NumberOptions): TInteger;
93
```
94

95
**Usage Examples:**
96

97
```typescript
98
// Basic integer
99
const Count = Type.Integer();
100

101
// Integer with range
102
const Port = Type.Integer({ minimum: 1, maximum: 65535 });
103
```
104

105
### Boolean Type
106

107
Creates a boolean type.
108

109
```typescript { .api }
110
/**
111
 * Creates a boolean type
112
 * @param options - Schema options
113
 * @returns TBoolean schema
114
 */
115
function Boolean(options?: SchemaOptions): TBoolean;
116
```
117

118
**Usage Examples:**
119

120
```typescript
121
// Basic boolean
122
const IsActive = Type.Boolean();
123

124
// Boolean with description
125
const HasPermission = Type.Boolean({ description: 'User has admin permissions' });
126
```
127

128
### Array Type
129

130
Creates an array type with item validation.
131

132
```typescript { .api }
133
/**
134
 * Creates an array type with item validation
135
 * @param items - Schema for array items
136
 * @param options - Array validation options
137
 * @returns TArray schema
138
 */
139
function Array<T extends TSchema>(items: T, options?: ArrayOptions): TArray<T>;
140

141
interface ArrayOptions extends SchemaOptions {
142
  minItems?: number;
143
  maxItems?: number;
144
  uniqueItems?: boolean;
145
  contains?: TSchema;
146
  minContains?: number;
147
  maxContains?: number;
148
}
149
```
150

151
**Usage Examples:**
152

153
```typescript
154
// Array of strings
155
const Tags = Type.Array(Type.String());
156

157
// Array with length constraints
158
const Items = Type.Array(Type.String(), { minItems: 1, maxItems: 10 });
159

160
// Array with unique items
161
const UniqueNumbers = Type.Array(Type.Number(), { uniqueItems: true });
162

163
// Array of objects
164
const Users = Type.Array(Type.Object({
165
  name: Type.String(),
166
  age: Type.Number()
167
}));
168
```
169

170
### Object Type
171

172
Creates an object type with property schemas.
173

174
```typescript { .api }
175
/**
176
 * Creates an object type with property schemas
177
 * @param properties - Object property schemas
178
 * @param options - Object validation options
179
 * @returns TObject schema
180
 */
181
function Object<T extends TProperties>(properties: T, options?: ObjectOptions): TObject<T>;
182

183
interface ObjectOptions extends SchemaOptions {
184
  additionalProperties?: boolean;
185
  minProperties?: number;
186
  maxProperties?: number;
187
}
188
```
189

190
**Usage Examples:**
191

192
```typescript
193
// Basic object
194
const Person = Type.Object({
195
  name: Type.String(),
196
  age: Type.Number(),
197
  email: Type.String({ format: 'email' })
198
});
199

200
// Object with optional properties
201
const User = Type.Object({
202
  id: Type.String(),
203
  name: Type.String(),
204
  bio: Type.Optional(Type.String())
205
});
206

207
// Object without additional properties
208
const StrictUser = Type.Object({
209
  name: Type.String(),
210
  age: Type.Number()
211
}, { additionalProperties: false });
212
```
213

214
### Union Type
215

216
Creates a union of multiple types (OR logic).
217

218
```typescript { .api }
219
/**
220
 * Creates a union of multiple types (OR logic)
221
 * @param types - Array of schemas to union
222
 * @param options - Schema options
223
 * @returns Union schema
224
 */
225
function Union<Types extends TSchema[]>(types: [...Types], options?: SchemaOptions): Union<Types>;
226
```
227

228
**Usage Examples:**
229

230
```typescript
231
// String or number
232
const StringOrNumber = Type.Union([Type.String(), Type.Number()]);
233

234
// Multiple object types
235
const AdminOrUser = Type.Union([
236
  Type.Object({ role: Type.Literal('admin'), permissions: Type.Array(Type.String()) }),
237
  Type.Object({ role: Type.Literal('user'), profile: Type.String() })
238
]);
239

240
// Nullable type
241
const NullableString = Type.Union([Type.String(), Type.Null()]);
242
```
243

244
### Literal Type
245

246
Creates a literal type for exact value matching.
247

248
```typescript { .api }
249
/**
250
 * Creates a literal type for exact value matching
251
 * @param value - The literal value
252
 * @returns TLiteral schema
253
 */
254
function Literal<T extends TLiteralValue>(value: T): TLiteral<T>;
255

256
type TLiteralValue = string | number | boolean;
257
```
258

259
**Usage Examples:**
260

261
```typescript
262
// String literal
263
const Status = Type.Literal('active');
264

265
// Number literal
266
const Version = Type.Literal(1);
267

268
// Boolean literal
269
const Enabled = Type.Literal(true);
270

271
// Union of literals (enum-like)
272
const Color = Type.Union([
273
  Type.Literal('red'),
274
  Type.Literal('green'),
275
  Type.Literal('blue')
276
]);
277
```
278

279
### Enum Type
280

281
Creates an enum type from object keys/values.
282

283
```typescript { .api }
284
/**
285
 * Creates an enum type from object keys/values
286
 * @param item - Enum object with string or number values
287
 * @param options - Schema options
288
 * @returns TEnum schema
289
 */
290
function Enum<V extends string | number, T extends Record<string, V>>(item: T, options?: SchemaOptions): TEnum<T>;
291
```
292

293
**Usage Examples:**
294

295
```typescript
296
// Enum from object
297
enum Color {
298
  Red = 'red',
299
  Green = 'green',
300
  Blue = 'blue'
301
}
302
const ColorEnum = Type.Enum(Color);
303

304
// Enum from numeric enum
305
enum Status {
306
  Pending = 0,
307
  Approved = 1,
308
  Rejected = 2
309
}
310
const StatusEnum = Type.Enum(Status);
311
```
312

313
### Null and Undefined
314

315
Creates null and undefined types.
316

317
```typescript { .api }
318
/**
319
 * Creates a null type
320
 * @param options - Schema options
321
 * @returns TNull schema
322
 */
323
function Null(options?: SchemaOptions): TNull;
324

325
/**
326
 * Creates an undefined type
327
 * @param options - Schema options  
328
 * @returns TUndefined schema
329
 */
330
function Undefined(options?: SchemaOptions): TUndefined;
331
```
332

333
### Tuple Type
334

335
Creates a tuple type with fixed element types and order.
336

337
```typescript { .api }
338
/**
339
 * Creates a tuple type with fixed element types and order
340
 * @param items - Array of schemas for tuple elements
341
 * @param options - Schema options
342
 * @returns TTuple schema
343
 */
344
function Tuple<T extends TSchema[]>(items: [...T], options?: SchemaOptions): TTuple<T>;
345
```
346

347
**Usage Examples:**
348

349
```typescript
350
// Basic tuple
351
const Point2D = Type.Tuple([Type.Number(), Type.Number()]);
352
// Type: [number, number]
353

354
// Mixed type tuple
355
const UserRecord = Type.Tuple([
356
  Type.String(), // id
357
  Type.String(), // name  
358
  Type.Number()  // age
359
]);
360
// Type: [string, string, number]
361

362
// Tuple with different types
363
const ApiResponse = Type.Tuple([
364
  Type.Number(),  // status code
365
  Type.String(),  // message
366
  Type.Any()      // data
367
]);
368
```
369

370
### Const Type
371

372
Creates a const type for deeply immutable literal values.
373

374
```typescript { .api }
375
/**
376
 * Creates a const type for deeply immutable literal values
377
 * @param value - The const value
378
 * @param options - Schema options
379
 * @returns TConst schema
380
 */
381
function Const<T extends TLiteralValue | object | any[]>(value: T, options?: SchemaOptions): TConst<T>;
382
```
383

384
**Usage Examples:**
385

386
```typescript
387
// Const primitive
388
const Status = Type.Const('active');
389

390
// Const object
391
const Config = Type.Const({
392
  version: 1,
393
  enabled: true,
394
  features: ['auth', 'logging']
395
});
396

397
// Const array
398
const DefaultTags = Type.Const(['user', 'active']);
399
```
400

401
### Any, Unknown, Never
402

403
Special utility types for flexible validation.
404

405
```typescript { .api }
406
/**
407
 * Creates an Any type that accepts all values
408
 * @param options - Schema options
409
 * @returns TAny schema
410
 */
411
function Any(options?: SchemaOptions): TAny;
412

413
/**
414
 * Creates an Unknown type (accepts all but requires type checking)
415
 * @param options - Schema options
416
 * @returns TUnknown schema
417
 */
418
function Unknown(options?: SchemaOptions): TUnknown;
419

420
/**
421
 * Creates a Never type (no valid values)
422
 * @param options - Schema options
423
 * @returns TNever schema
424
 */
425
function Never(options?: SchemaOptions): TNever;
426
```
427

428
## Type Interfaces
429

430
```typescript { .api }
431
interface TString extends TSchema {
432
  type: 'string';
433
  minLength?: number;
434
  maxLength?: number;
435
  pattern?: string;
436
  format?: string;
437
}
438

439
interface TNumber extends TSchema {
440
  type: 'number';
441
  minimum?: number;
442
  maximum?: number;
443
  exclusiveMinimum?: number;
444
  exclusiveMaximum?: number;
445
  multipleOf?: number;
446
}
447

448
interface TInteger extends TSchema {
449
  type: 'integer';
450
  minimum?: number;
451
  maximum?: number;
452
  exclusiveMinimum?: number;
453
  exclusiveMaximum?: number;
454
  multipleOf?: number;
455
}
456

457
interface TBoolean extends TSchema {
458
  type: 'boolean';
459
}
460

461
interface TArray<T extends TSchema> extends TSchema {
462
  type: 'array';
463
  items: T;
464
  minItems?: number;
465
  maxItems?: number;
466
  uniqueItems?: boolean;
467
}
468

469
interface TObject<T extends TProperties> extends TSchema {
470
  type: 'object';
471
  properties: T;
472
  required?: string[];
473
  additionalProperties?: boolean;
474
  minProperties?: number;
475
  maxProperties?: number;
476
}
477

478
interface TUnion<T extends TSchema[]> extends TSchema {
479
  anyOf: T;
480
}
481

482
interface TLiteral<T extends TLiteralValue> extends TSchema {
483
  const: T;
484
}
485

486
interface TEnum<T> extends TSchema {
487
  enum: T extends readonly any[] ? T : T extends Record<string, infer U> ? U[] : never;
488
}
489

490
interface TNull extends TSchema {
491
  type: 'null';
492
}
493

494
interface TUndefined extends TSchema {
495
  not: {};
496
}
497

498
interface TAny extends TSchema {
499
  // No type constraint
500
}
501

502
interface TUnknown extends TSchema {
503
  // No type constraint
504
}
505

506
interface TNever extends TSchema {
507
  not: {};
508
}
509

510
interface TTuple<T extends TSchema[]> extends TSchema {
511
  type: 'array';
512
  items: T;
513
  minItems: T['length'];
514
  maxItems: T['length'];
515
  additionalItems: false;
516
}
517

518
interface TConst<T> extends TSchema {
519
  const: T;
520
}
521

522
interface TVoid extends TSchema {
523
  type: 'null';
524
}
525
```