0
# JSON Schema Types
1

2
The `JSONSchema` namespace provides comprehensive JSON Schema Draft 04 types for defining ESLint rule configurations with full type safety.
3

4
## Import
5

6
```typescript { .api }
7
import { JSONSchema } from '@typescript-eslint/utils';
8
```
9

10
## Basic Types
11

12
### JSON Schema Type Names
13

14
```typescript { .api }
15
// Valid JSON Schema type names
16
type JSONSchema4TypeName = 
17
  | 'any' 
18
  | 'array' 
19
  | 'boolean' 
20
  | 'integer' 
21
  | 'null' 
22
  | 'number' 
23
  | 'object' 
24
  | 'string';
25

26
// Basic JSON values
27
type JSONSchema4Type = boolean | number | string | null;
28

29
// Extended JSON types including arrays and objects
30
type JSONSchema4TypeExtended = 
31
  | JSONSchema4Type
32
  | JSONSchema4Object
33
  | JSONSchema4Array;
34

35
// JSON Schema version identifier
36
type JSONSchema4Version = string;
37
```
38

39
### Collection Types
40

41
```typescript { .api }
42
// Object with string keys and extended JSON values
43
interface JSONSchema4Object {
44
  [key: string]: JSONSchema4TypeExtended;
45
}
46

47
// Array of extended JSON values
48
interface JSONSchema4Array extends Array<JSONSchema4TypeExtended> {}
49
```
50

51
## Core Schema Interface
52

53
### Base Schema Properties
54

55
```typescript { .api }
56
interface JSONSchema4Base {
57
  // Schema metadata
58
  $schema?: JSONSchema4Version;
59
  $ref?: string;
60
  title?: string;
61
  description?: string;
62
  
63
  // Default value
64
  default?: JSONSchema4TypeExtended;
65
  
66
  // Schema composition
67
  allOf?: JSONSchema4[];
68
  anyOf?: JSONSchema4[];
69
  oneOf?: JSONSchema4[];
70
  not?: JSONSchema4;
71
  
72
  // Type specification
73
  type?: JSONSchema4TypeName | JSONSchema4TypeName[];
74
  
75
  // Definitions and references
76
  definitions?: { [key: string]: JSONSchema4 };
77
  $defs?: { [key: string]: JSONSchema4 };
78
  
79
  // Enumeration
80
  enum?: JSONSchema4TypeExtended[];
81
  
82
  // Conditional schemas
83
  if?: JSONSchema4;
84
  then?: JSONSchema4;
85
  else?: JSONSchema4;
86
}
87
```
88

89
## Specific Schema Types
90

91
### Reference Schema
92

93
```typescript { .api }
94
interface JSONSchema4RefSchema extends JSONSchema4Base {
95
  $ref: string;
96
}
97

98
// Usage example
99
const refSchema: JSONSchema.JSONSchema4RefSchema = {
100
  $ref: '#/definitions/MyType'
101
};
102
```
103

104
### Composition Schemas
105

106
```typescript { .api }
107
// AllOf schema - AND logic
108
interface JSONSchema4AllOfSchema extends JSONSchema4Base {
109
  allOf: JSONSchema4[];
110
}
111

112
// AnyOf schema - OR logic  
113
interface JSONSchema4AnyOfSchema extends JSONSchema4Base {
114
  anyOf: JSONSchema4[];
115
}
116

117
// OneOf schema - XOR logic
118
interface JSONSchema4OneOfSchema extends JSONSchema4Base {
119
  oneOf: JSONSchema4[];
120
}
121

122
// Usage examples
123
const allOfSchema: JSONSchema.JSONSchema4AllOfSchema = {
124
  allOf: [
125
    { type: 'object' },
126
    { 
127
      properties: {
128
        name: { type: 'string' }
129
      }
130
    }
131
  ]
132
};
133

134
const anyOfSchema: JSONSchema.JSONSchema4AnyOfSchema = {
135
  anyOf: [
136
    { type: 'string' },
137
    { type: 'number' }
138
  ]
139
};
140
```
141

142
### Multiple Type Schema
143

144
```typescript { .api }
145
interface JSONSchema4MultiSchema extends JSONSchema4Base {
146
  type: JSONSchema4TypeName[];
147
}
148

149
// Usage example
150
const multiTypeSchema: JSONSchema.JSONSchema4MultiSchema = {
151
  type: ['string', 'number'],
152
  description: 'String or number value'
153
};
154
```
155

156
## Object Schema
157

158
### Object Schema Definition
159

160
```typescript { .api }
161
interface JSONSchema4ObjectSchema extends JSONSchema4Base {
162
  type: 'object';
163
  
164
  // Property definitions
165
  properties?: { [key: string]: JSONSchema4 };
166
  additionalProperties?: boolean | JSONSchema4;
167
  
168
  // Property requirements
169
  required?: string[];
170
  
171
  // Property count constraints
172
  minProperties?: number;
173
  maxProperties?: number;
174
  
175
  // Property name patterns
176
  patternProperties?: { [pattern: string]: JSONSchema4 };
177
  
178
  // Property dependencies
179
  dependencies?: {
180
    [key: string]: JSONSchema4 | string[];
181
  };
182
  
183
  // Property names validation
184
  propertyNames?: JSONSchema4;
185
}
186
```
187

188
### Object Schema Examples
189

190
```typescript { .api }
191
// Simple object schema
192
const userSchema: JSONSchema.JSONSchema4ObjectSchema = {
193
  type: 'object',
194
  properties: {
195
    name: { type: 'string' },
196
    age: { type: 'integer', minimum: 0 },
197
    email: { 
198
      type: 'string',
199
      format: 'email'
200
    }
201
  },
202
  required: ['name', 'email'],
203
  additionalProperties: false
204
};
205

206
// Object with pattern properties
207
const configSchema: JSONSchema.JSONSchema4ObjectSchema = {
208
  type: 'object',
209
  properties: {
210
    version: { type: 'string' }
211
  },
212
  patternProperties: {
213
    '^rule-.+': {
214
      type: 'object',
215
      properties: {
216
        enabled: { type: 'boolean' },
217
        level: { enum: ['error', 'warn', 'off'] }
218
      }
219
    }
220
  },
221
  additionalProperties: false
222
};
223

224
// Object with dependencies
225
const conditionalSchema: JSONSchema.JSONSchema4ObjectSchema = {
226
  type: 'object',
227
  properties: {
228
    useCache: { type: 'boolean' },
229
    cacheDir: { type: 'string' },
230
    cacheTTL: { type: 'integer' }
231
  },
232
  dependencies: {
233
    cacheDir: ['useCache'],
234
    cacheTTL: ['useCache']
235
  }
236
};
237
```
238

239
## Array Schema
240

241
### Array Schema Definition
242

243
```typescript { .api }
244
interface JSONSchema4ArraySchema extends JSONSchema4Base {
245
  type: 'array';
246
  
247
  // Item validation
248
  items?: JSONSchema4 | JSONSchema4[];
249
  additionalItems?: boolean | JSONSchema4;
250
  
251
  // Length constraints
252
  minItems?: number;
253
  maxItems?: number;
254
  
255
  // Uniqueness
256
  uniqueItems?: boolean;
257
  
258
  // Contains validation (Draft 6+, but commonly supported)
259
  contains?: JSONSchema4;
260
}
261
```
262

263
### Array Schema Examples
264

265
```typescript { .api }
266
// Simple array schema
267
const stringArraySchema: JSONSchema.JSONSchema4ArraySchema = {
268
  type: 'array',
269
  items: { type: 'string' },
270
  minItems: 1,
271
  uniqueItems: true
272
};
273

274
// Tuple schema with specific items
275
const tupleSchema: JSONSchema.JSONSchema4ArraySchema = {
276
  type: 'array',
277
  items: [
278
    { type: 'string' },
279
    { type: 'number' },
280
    { type: 'boolean' }
281
  ],
282
  additionalItems: false,
283
  minItems: 2,
284
  maxItems: 3
285
};
286

287
// Array with complex item validation
288
const complexArraySchema: JSONSchema.JSONSchema4ArraySchema = {
289
  type: 'array',
290
  items: {
291
    type: 'object',
292
    properties: {
293
      id: { type: 'integer' },
294
      name: { type: 'string' },
295
      tags: {
296
        type: 'array',
297
        items: { type: 'string' }
298
      }
299
    },
300
    required: ['id', 'name']
301
  },
302
  minItems: 0,
303
  maxItems: 100
304
};
305
```
306

307
## String Schema
308

309
### String Schema Definition
310

311
```typescript { .api }
312
interface JSONSchema4StringSchema extends JSONSchema4Base {
313
  type: 'string';
314
  
315
  // Length constraints
316
  minLength?: number;
317
  maxLength?: number;
318
  
319
  // Pattern matching
320
  pattern?: string;
321
  
322
  // Format validation
323
  format?: 
324
    | 'date-time'
325
    | 'date'
326
    | 'time'
327
    | 'email'
328
    | 'hostname'
329
    | 'ipv4'
330
    | 'ipv6'
331
    | 'uri'
332
    | 'uri-reference'
333
    | 'regex'
334
    | string;
335
}
336
```
337

338
### String Schema Examples
339

340
```typescript { .api }
341
// Basic string validation
342
const nameSchema: JSONSchema.JSONSchema4StringSchema = {
343
  type: 'string',
344
  minLength: 1,
345
  maxLength: 100,
346
  pattern: '^[A-Za-z\\s]+$'
347
};
348

349
// Email format validation
350
const emailSchema: JSONSchema.JSONSchema4StringSchema = {
351
  type: 'string',
352
  format: 'email'
353
};
354

355
// Enum string values
356
const modeSchema: JSONSchema.JSONSchema4StringSchema = {
357
  type: 'string',
358
  enum: ['strict', 'loose', 'off']
359
};
360

361
// Pattern-based validation
362
const identifierSchema: JSONSchema.JSONSchema4StringSchema = {
363
  type: 'string',
364
  pattern: '^[a-zA-Z_][a-zA-Z0-9_]*$',
365
  description: 'Valid JavaScript identifier'
366
};
367
```
368

369
## Number Schema
370

371
### Number Schema Definition
372

373
```typescript { .api }
374
interface JSONSchema4NumberSchema extends JSONSchema4Base {
375
  type: 'number' | 'integer';
376
  
377
  // Range constraints
378
  minimum?: number;
379
  maximum?: number;
380
  exclusiveMinimum?: boolean | number;
381
  exclusiveMaximum?: boolean | number;
382
  
383
  // Multiple validation
384
  multipleOf?: number;
385
}
386
```
387

388
### Number Schema Examples
389

390
```typescript { .api }
391
// Integer with range
392
const portSchema: JSONSchema.JSONSchema4NumberSchema = {
393
  type: 'integer',
394
  minimum: 1,
395
  maximum: 65535
396
};
397

398
// Float with precision
399
const percentageSchema: JSONSchema.JSONSchema4NumberSchema = {
400
  type: 'number',
401
  minimum: 0,
402
  maximum: 100,
403
  multipleOf: 0.01
404
};
405

406
// Exclusive bounds
407
const positiveNumberSchema: JSONSchema.JSONSchema4NumberSchema = {
408
  type: 'number',
409
  exclusiveMinimum: true,
410
  minimum: 0
411
};
412
```
413

414
## Other Schema Types
415

416
### Boolean Schema
417

418
```typescript { .api }
419
interface JSONSchema4BooleanSchema extends JSONSchema4Base {
420
  type: 'boolean';
421
}
422

423
const booleanSchema: JSONSchema.JSONSchema4BooleanSchema = {
424
  type: 'boolean',
425
  default: false
426
};
427
```
428

429
### Null Schema
430

431
```typescript { .api }
432
interface JSONSchema4NullSchema extends JSONSchema4Base {
433
  type: 'null';
434
}
435

436
const nullSchema: JSONSchema.JSONSchema4NullSchema = {
437
  type: 'null'
438
};
439
```
440

441
### Any Schema
442

443
```typescript { .api }
444
interface JSONSchema4AnySchema extends JSONSchema4Base {
445
  type?: 'any';
446
}
447

448
const anyValueSchema: JSONSchema.JSONSchema4AnySchema = {
449
  description: 'Any value is allowed'
450
};
451
```
452

453
## Main Union Type
454

455
### Complete Schema Type
456

457
```typescript { .api }
458
// Main JSON Schema type - union of all schema types
459
type JSONSchema4 =
460
  | JSONSchema4RefSchema
461
  | JSONSchema4AllOfSchema
462
  | JSONSchema4AnyOfSchema
463
  | JSONSchema4OneOfSchema
464
  | JSONSchema4MultiSchema
465
  | JSONSchema4ObjectSchema
466
  | JSONSchema4ArraySchema
467
  | JSONSchema4StringSchema
468
  | JSONSchema4NumberSchema
469
  | JSONSchema4BooleanSchema
470
  | JSONSchema4NullSchema
471
  | JSONSchema4AnySchema
472
  | boolean; // Boolean schemas (true = allow any, false = allow none)
473
```
474

475
## ESLint Rule Schema Examples
476

477
### Simple Rule Configuration
478

479
```typescript { .api }
480
// Basic boolean option
481
const simpleBooleanSchema: JSONSchema.JSONSchema4 = {
482
  type: 'boolean'
483
};
484

485
// Simple object configuration
486
const basicConfigSchema: JSONSchema.JSONSchema4 = {
487
  type: 'object',
488
  properties: {
489
    enabled: { type: 'boolean' },
490
    level: { 
491
      type: 'string',
492
      enum: ['error', 'warn', 'off']
493
    }
494
  },
495
  additionalProperties: false
496
};
497
```
498

499
### Complex Rule Configuration
500

501
```typescript { .api }
502
// Array of options with different types
503
const complexRuleSchema: JSONSchema.JSONSchema4[] = [
504
  {
505
    // First option: mode selection
506
    type: 'string',
507
    enum: ['strict', 'loose', 'off']
508
  },
509
  {
510
    // Second option: detailed configuration
511
    type: 'object',
512
    properties: {
513
      exceptions: {
514
        type: 'array',
515
        items: { type: 'string' },
516
        uniqueItems: true
517
      },
518
      ignorePatterns: {
519
        type: 'array',
520
        items: {
521
          type: 'string',
522
          format: 'regex'
523
        }
524
      },
525
      overrides: {
526
        type: 'object',
527
        patternProperties: {
528
          '.*': {
529
            type: 'object',
530
            properties: {
531
              mode: { enum: ['strict', 'loose', 'inherit'] },
532
              exceptions: {
533
                type: 'array',
534
                items: { type: 'string' }
535
              }
536
            },
537
            additionalProperties: false
538
          }
539
        }
540
      }
541
    },
542
    additionalProperties: false
543
  }
544
];
545
```
546

547
### Conditional Schema
548

549
```typescript { .api }
550
// Schema with conditional validation
551
const conditionalRuleSchema: JSONSchema.JSONSchema4 = {
552
  type: 'object',
553
  properties: {
554
    mode: {
555
      type: 'string',
556
      enum: ['manual', 'auto']
557
    },
558
    manualConfig: {
559
      type: 'object',
560
      properties: {
561
        patterns: {
562
          type: 'array',
563
          items: { type: 'string' }
564
        }
565
      }
566
    },
567
    autoConfig: {
568
      type: 'object',
569
      properties: {
570
        threshold: { type: 'number' },
571
        recursive: { type: 'boolean' }
572
      }
573
    }
574
  },
575
  allOf: [
576
    {
577
      if: {
578
        properties: { mode: { const: 'manual' } }
579
      },
580
      then: {
581
        required: ['manualConfig'],
582
        not: {
583
          required: ['autoConfig']
584
        }
585
      }
586
    },
587
    {
588
      if: {
589
        properties: { mode: { const: 'auto' } }
590
      },
591
      then: {
592
        required: ['autoConfig'],
593
        not: {
594
          required: ['manualConfig']
595
        }
596
      }
597
    }
598
  ],
599
  required: ['mode']
600
};
601
```
602

603
## Type-Safe Rule Creation
604

605
### Using Schemas in Rules
606

607
```typescript { .api }
608
import { ESLintUtils, JSONSchema } from '@typescript-eslint/utils';
609

610
// Define schema with full typing
611
const ruleOptionsSchema: JSONSchema.JSONSchema4[] = [
612
  {
613
    type: 'object',
614
    properties: {
615
      checkReturns: { type: 'boolean' },
616
      checkParams: { type: 'boolean' },
617
      ignorePrivate: { type: 'boolean' },
618
      patterns: {
619
        type: 'array',
620
        items: { type: 'string' },
621
        minItems: 0
622
      }
623
    },
624
    additionalProperties: false
625
  }
626
];
627

628
type Options = [{
629
  checkReturns?: boolean;
630
  checkParams?: boolean;
631
  ignorePrivate?: boolean;
632
  patterns?: string[];
633
}];
634

635
const createRule = ESLintUtils.RuleCreator(name => `https://example.com/${name}`);
636

637
export default createRule<Options, 'missingType'>({
638
  name: 'typed-rule-example',
639
  meta: {
640
    type: 'problem',
641
    docs: {
642
      description: 'Example of type-safe rule with JSON Schema'
643
    },
644
    messages: {
645
      missingType: 'Missing type annotation'
646
    },
647
    schema: ruleOptionsSchema // Fully typed schema
648
  },
649
  defaultOptions: [{
650
    checkReturns: true,
651
    checkParams: true,
652
    ignorePrivate: false,
653
    patterns: []
654
  }],
655
  create(context, [options]) {
656
    // options is fully typed based on schema
657
    const { checkReturns, checkParams, ignorePrivate, patterns } = options;
658
    
659
    return {
660
      FunctionDeclaration(node) {
661
        if (ignorePrivate && node.id?.name.startsWith('_')) {
662
          return;
663
        }
664
        
665
        // Rule implementation using typed options
666
      }
667
    };
668
  }
669
});
670
```
671

672
### Schema Validation Utilities
673

674
```typescript { .api }
675
// Helper to create strict object schemas
676
function createStrictObjectSchema(properties: Record<string, JSONSchema.JSONSchema4>): JSONSchema.JSONSchema4ObjectSchema {
677
  return {
678
    type: 'object',
679
    properties,
680
    additionalProperties: false
681
  };
682
}
683

684
// Helper to create enum schemas
685
function createEnumSchema<T extends readonly string[]>(values: T): JSONSchema.JSONSchema4StringSchema {
686
  return {
687
    type: 'string',
688
    enum: [...values]
689
  };
690
}
691

692
// Usage examples
693
const strictConfigSchema = createStrictObjectSchema({
694
  mode: createEnumSchema(['strict', 'loose'] as const),
695
  level: createEnumSchema(['error', 'warn'] as const),
696
  enabled: { type: 'boolean' }
697
});
698

699
// Array schema helper
700
function createArraySchema(itemSchema: JSONSchema.JSONSchema4, options?: {
701
  minItems?: number;
702
  maxItems?: number;
703
  uniqueItems?: boolean;
704
}): JSONSchema.JSONSchema4ArraySchema {
705
  return {
706
    type: 'array',
707
    items: itemSchema,
708
    ...options
709
  };
710
}
711

712
const stringArraySchema = createArraySchema(
713
  { type: 'string', minLength: 1 },
714
  { minItems: 0, uniqueItems: true }
715
);
716
```
717

718
## Complete Rule Schema Example
719

720
```typescript { .api }
721
import { ESLintUtils, JSONSchema } from '@typescript-eslint/utils';
722

723
// Comprehensive rule schema
724
const comprehensiveRuleSchema: JSONSchema.JSONSchema4[] = [
725
  {
726
    type: 'object',
727
    properties: {
728
      // Basic options
729
      enabled: { type: 'boolean' },
730
      severity: {
731
        type: 'string', 
732
        enum: ['error', 'warning', 'suggestion']
733
      },
734
      
735
      // Array configurations
736
      ignorePatterns: {
737
        type: 'array',
738
        items: { 
739
          type: 'string',
740
          minLength: 1
741
        },
742
        uniqueItems: true
743
      },
744
      
745
      // Nested object configuration
746
      typeChecking: {
747
        type: 'object',
748
        properties: {
749
          enabled: { type: 'boolean' },
750
          strictMode: { type: 'boolean' },
751
          allowedTypes: {
752
            type: 'array',
753
            items: {
754
              type: 'string',
755
              enum: ['string', 'number', 'boolean', 'object', 'array']
756
            }
757
          }
758
        },
759
        additionalProperties: false,
760
        required: ['enabled']
761
      },
762
      
763
      // Conditional configuration
764
      advanced: {
765
        type: 'object',
766
        properties: {
767
          mode: { enum: ['auto', 'manual'] },
768
          autoSettings: {
769
            type: 'object',
770
            properties: {
771
              threshold: { type: 'number', minimum: 0, maximum: 1 }
772
            }
773
          },
774
          manualSettings: {
775
            type: 'object',
776
            properties: {
777
              rules: {
778
                type: 'array',
779
                items: { type: 'string' }
780
              }
781
            }
782
          }
783
        },
784
        allOf: [
785
          {
786
            if: { properties: { mode: { const: 'auto' } } },
787
            then: { required: ['autoSettings'] }
788
          },
789
          {
790
            if: { properties: { mode: { const: 'manual' } } },
791
            then: { required: ['manualSettings'] }
792
          }
793
        ]
794
      }
795
    },
796
    additionalProperties: false
797
  }
798
];
799

800
type ComplexOptions = [{
801
  enabled?: boolean;
802
  severity?: 'error' | 'warning' | 'suggestion';
803
  ignorePatterns?: string[];
804
  typeChecking?: {
805
    enabled: boolean;
806
    strictMode?: boolean;
807
    allowedTypes?: Array<'string' | 'number' | 'boolean' | 'object' | 'array'>;
808
  };
809
  advanced?: {
810
    mode: 'auto' | 'manual';
811
    autoSettings?: { threshold: number };
812
    manualSettings?: { rules: string[] };
813
  };
814
}];
815

816
const createRule = ESLintUtils.RuleCreator(name => `https://example.com/${name}`);
817

818
export default createRule<ComplexOptions, 'violation'>({
819
  name: 'comprehensive-schema-example',
820
  meta: {
821
    type: 'problem',
822
    docs: { description: 'Demonstrates comprehensive JSON Schema usage' },
823
    messages: { violation: 'Rule violation detected' },
824
    schema: comprehensiveRuleSchema
825
  },
826
  defaultOptions: [{
827
    enabled: true,
828
    severity: 'error',
829
    ignorePatterns: [],
830
    typeChecking: { enabled: true }
831
  }],
832
  create(context, [options]) {
833
    // Fully typed options with schema validation
834
    return {
835
      Program() {
836
        // Implementation using validated options
837
      }
838
    };
839
  }
840
});
841
```