0
# JSON Schema Types
1

2
Complete JSON Schema type definitions for rule configuration schemas. This module provides comprehensive TypeScript types for JSON Schema drafts 4, 6, and 7, enabling type-safe rule option validation and configuration.
3

4
## Capabilities
5

6
### JSON Schema Draft 7 Types
7

8
The primary JSON Schema types used for ESLint rule configuration.
9

10
```typescript { .api }
11
/**
12
 * JSON Schema Draft 7 - primary schema interface
13
 */
14
interface JSONSchema7 {
15
  /** Schema identifier */
16
  $id?: string;
17
  /** Schema reference */
18
  $ref?: string;
19
  /** Schema dialect */
20
  $schema?: string;
21
  /** Schema comment */
22
  $comment?: string;
23
  /** Schema definitions */
24
  $defs?: Record<string, JSONSchema7Definition>;
25
  
26
  // Annotation keywords
27
  /** Schema title */
28
  title?: string;
29
  /** Schema description */
30
  description?: string;
31
  /** Default value */
32
  default?: JSONSchema7Type;
33
  /** Whether the instance is read-only */
34
  readOnly?: boolean;
35
  /** Whether the instance is write-only */
36
  writeOnly?: boolean;
37
  /** Example values */
38
  examples?: JSONSchema7Type[];
39
  
40
  // Validation keywords for numeric instances
41
  /** Value must be a multiple of this number */
42
  multipleOf?: number;
43
  /** Maximum value (inclusive) */
44
  maximum?: number;
45
  /** Exclusive maximum value */
46
  exclusiveMaximum?: number;
47
  /** Minimum value (inclusive) */
48
  minimum?: number;
49
  /** Exclusive minimum value */
50
  exclusiveMinimum?: number;
51
  
52
  // Validation keywords for strings
53
  /** Maximum string length */
54
  maxLength?: number;
55
  /** Minimum string length */
56
  minLength?: number;
57
  /** Regular expression pattern */
58
  pattern?: string;
59
  
60
  // Validation keywords for arrays
61
  /** Schema for additional array items */
62
  additionalItems?: JSONSchema7Definition;
63
  /** Schema(s) for array items */
64
  items?: JSONSchema7Definition | JSONSchema7Definition[];
65
  /** Maximum array length */
66
  maxItems?: number;
67
  /** Minimum array length */
68
  minItems?: number;
69
  /** Whether array items must be unique */
70
  uniqueItems?: boolean;
71
  /** Schema that at least one item must match */
72
  contains?: JSONSchema7Definition;
73
  
74
  // Validation keywords for objects
75
  /** Maximum number of properties */
76
  maxProperties?: number;
77
  /** Minimum number of properties */
78
  minProperties?: number;
79
  /** Required property names */
80
  required?: string[];
81
  /** Schema for additional properties */
82
  additionalProperties?: JSONSchema7Definition;
83
  /** Legacy schema definitions */
84
  definitions?: Record<string, JSONSchema7Definition>;
85
  /** Schema for known properties */
86
  properties?: Record<string, JSONSchema7Definition>;
87
  /** Schema for properties matching patterns */
88
  patternProperties?: Record<string, JSONSchema7Definition>;
89
  /** Dependencies between properties */
90
  dependencies?: Record<string, JSONSchema7Definition | string[]>;
91
  /** Schema for property names */
92
  propertyNames?: JSONSchema7Definition;
93
  
94
  // Validation keywords for any instance type
95
  /** Constant value */
96
  const?: JSONSchema7Type;
97
  /** Enumeration of valid values */
98
  enum?: JSONSchema7Type[];
99
  /** Expected type(s) */
100
  type?: JSONSchema7TypeName | JSONSchema7TypeName[];
101
  
102
  // String format validation
103
  /** String format specification */
104
  format?: string;
105
  /** Content media type */
106
  contentMediaType?: string;
107
  /** Content encoding */
108
  contentEncoding?: string;
109
  
110
  // Conditional validation
111
  /** If schema */
112
  if?: JSONSchema7Definition;
113
  /** Then schema (used with if) */
114
  then?: JSONSchema7Definition;
115
  /** Else schema (used with if) */
116
  else?: JSONSchema7Definition;
117
  
118
  // Schema composition
119
  /** All schemas must match */
120
  allOf?: JSONSchema7Definition[];
121
  /** At least one schema must match */
122
  anyOf?: JSONSchema7Definition[];
123
  /** Exactly one schema must match */
124
  oneOf?: JSONSchema7Definition[];
125
  /** Schema must not match */
126
  not?: JSONSchema7Definition;
127
}
128

129
/**
130
 * JSON Schema Draft 7 definition - can be a boolean or schema object
131
 */
132
type JSONSchema7Definition = boolean | JSONSchema7;
133

134
/**
135
 * JSON Schema Draft 7 type names
136
 */
137
type JSONSchema7TypeName = 
138
  | 'string' 
139
  | 'number' 
140
  | 'integer' 
141
  | 'boolean' 
142
  | 'object' 
143
  | 'array' 
144
  | 'null';
145

146
/**
147
 * JSON Schema Draft 7 value types
148
 */
149
type JSONSchema7Type = 
150
  | string 
151
  | number 
152
  | boolean 
153
  | JSONSchema7Object 
154
  | JSONSchema7Array 
155
  | null;
156

157
/**
158
 * JSON Schema Draft 7 object type
159
 */
160
interface JSONSchema7Object {
161
  [key: string]: JSONSchema7Type;
162
}
163

164
/**
165
 * JSON Schema Draft 7 array type
166
 */
167
interface JSONSchema7Array extends Array<JSONSchema7Type> {}
168

169
/**
170
 * JSON Schema Draft 7 version identifier
171
 */
172
type JSONSchema7Version = 'http://json-schema.org/draft-07/schema#';
173
```
174

175
### JSON Schema Draft 6 Types
176

177
Previous version of JSON Schema with slightly different features.
178

179
```typescript { .api }
180
/**
181
 * JSON Schema Draft 6 interface
182
 */
183
interface JSONSchema6 {
184
  /** Schema identifier */
185
  $id?: string;
186
  /** Schema reference */
187
  $ref?: string;
188
  /** Schema dialect */
189
  $schema?: string;
190
  
191
  // Annotation keywords
192
  /** Schema title */
193
  title?: string;
194
  /** Schema description */
195
  description?: string;
196
  /** Default value */
197
  default?: JSONSchema6Type;
198
  /** Example values */
199
  examples?: JSONSchema6Type[];
200
  
201
  // Numeric validation
202
  /** Value must be a multiple of this number */
203
  multipleOf?: number;
204
  /** Maximum value (inclusive) */
205
  maximum?: number;
206
  /** Exclusive maximum value */
207
  exclusiveMaximum?: number;
208
  /** Minimum value (inclusive) */
209
  minimum?: number;
210
  /** Exclusive minimum value */
211
  exclusiveMinimum?: number;
212
  
213
  // String validation
214
  /** Maximum string length */
215
  maxLength?: number;
216
  /** Minimum string length */
217
  minLength?: number;
218
  /** Regular expression pattern */
219
  pattern?: string;
220
  
221
  // Array validation
222
  /** Schema for additional array items */
223
  additionalItems?: JSONSchema6Definition;
224
  /** Schema(s) for array items */
225
  items?: JSONSchema6Definition | JSONSchema6Definition[];
226
  /** Maximum array length */
227
  maxItems?: number;
228
  /** Minimum array length */
229
  minItems?: number;
230
  /** Whether array items must be unique */
231
  uniqueItems?: boolean;
232
  /** Schema that at least one item must match */
233
  contains?: JSONSchema6Definition;
234
  
235
  // Object validation
236
  /** Maximum number of properties */
237
  maxProperties?: number;
238
  /** Minimum number of properties */
239
  minProperties?: number;
240
  /** Required property names */
241
  required?: string[];
242
  /** Schema for additional properties */
243
  additionalProperties?: JSONSchema6Definition;
244
  /** Schema definitions */
245
  definitions?: Record<string, JSONSchema6Definition>;
246
  /** Schema for known properties */
247
  properties?: Record<string, JSONSchema6Definition>;
248
  /** Schema for properties matching patterns */
249
  patternProperties?: Record<string, JSONSchema6Definition>;
250
  /** Dependencies between properties */
251
  dependencies?: Record<string, JSONSchema6Definition | string[]>;
252
  /** Schema for property names */
253
  propertyNames?: JSONSchema6Definition;
254
  
255
  // Type validation
256
  /** Constant value */
257
  const?: JSONSchema6Type;
258
  /** Enumeration of valid values */
259
  enum?: JSONSchema6Type[];
260
  /** Expected type(s) */
261
  type?: JSONSchema6TypeName | JSONSchema6TypeName[];
262
  
263
  // String format
264
  /** String format specification */
265
  format?: string;
266
  
267
  // Schema composition
268
  /** All schemas must match */
269
  allOf?: JSONSchema6Definition[];
270
  /** At least one schema must match */
271
  anyOf?: JSONSchema6Definition[];
272
  /** Exactly one schema must match */
273
  oneOf?: JSONSchema6Definition[];
274
  /** Schema must not match */
275
  not?: JSONSchema6Definition;
276
}
277

278
/**
279
 * JSON Schema Draft 6 definition
280
 */
281
type JSONSchema6Definition = boolean | JSONSchema6;
282

283
/**
284
 * JSON Schema Draft 6 type names
285
 */
286
type JSONSchema6TypeName = 
287
  | 'string' 
288
  | 'number' 
289
  | 'integer' 
290
  | 'boolean' 
291
  | 'object' 
292
  | 'array' 
293
  | 'null';
294

295
/**
296
 * JSON Schema Draft 6 value types
297
 */
298
type JSONSchema6Type = 
299
  | string 
300
  | number 
301
  | boolean 
302
  | JSONSchema6Object 
303
  | JSONSchema6Array 
304
  | null;
305

306
/**
307
 * JSON Schema Draft 6 object type
308
 */
309
interface JSONSchema6Object {
310
  [key: string]: JSONSchema6Type;
311
}
312

313
/**
314
 * JSON Schema Draft 6 array type
315
 */
316
interface JSONSchema6Array extends Array<JSONSchema6Type> {}
317

318
/**
319
 * JSON Schema Draft 6 version identifier
320
 */
321
type JSONSchema6Version = 'http://json-schema.org/draft-06/schema#';
322
```
323

324
### JSON Schema Draft 4 Types
325

326
Legacy JSON Schema version still used in some contexts.
327

328
```typescript { .api }
329
/**
330
 * JSON Schema Draft 4 interface
331
 */
332
interface JSONSchema4 {
333
  /** Schema identifier */
334
  id?: string;
335
  /** Schema reference */
336
  $ref?: string;
337
  /** Schema dialect */
338
  $schema?: string;
339
  
340
  // Annotation keywords
341
  /** Schema title */
342
  title?: string;
343
  /** Schema description */
344
  description?: string;
345
  /** Default value */
346
  default?: JSONSchema4Type;
347
  
348
  // Numeric validation
349
  /** Value must be a multiple of this number */
350
  multipleOf?: number;
351
  /** Maximum value (inclusive) */
352
  maximum?: number;
353
  /** Whether maximum is exclusive */
354
  exclusiveMaximum?: boolean;
355
  /** Minimum value (inclusive) */
356
  minimum?: number;
357
  /** Whether minimum is exclusive */
358
  exclusiveMinimum?: boolean;
359
  
360
  // String validation
361
  /** Maximum string length */
362
  maxLength?: number;
363
  /** Minimum string length */
364
  minLength?: number;
365
  /** Regular expression pattern */
366
  pattern?: string;
367
  
368
  // Array validation
369
  /** Schema for additional array items */
370
  additionalItems?: boolean | JSONSchema4;
371
  /** Schema(s) for array items */
372
  items?: JSONSchema4 | JSONSchema4[];
373
  /** Maximum array length */
374
  maxItems?: number;
375
  /** Minimum array length */
376
  minItems?: number;
377
  /** Whether array items must be unique */
378
  uniqueItems?: boolean;
379
  
380
  // Object validation
381
  /** Maximum number of properties */
382
  maxProperties?: number;
383
  /** Minimum number of properties */
384
  minProperties?: number;
385
  /** Required property names */
386
  required?: string[];
387
  /** Schema for additional properties */
388
  additionalProperties?: boolean | JSONSchema4;
389
  /** Schema definitions */
390
  definitions?: Record<string, JSONSchema4>;
391
  /** Schema for known properties */
392
  properties?: Record<string, JSONSchema4>;
393
  /** Schema for properties matching patterns */
394
  patternProperties?: Record<string, JSONSchema4>;
395
  /** Dependencies between properties */
396
  dependencies?: Record<string, JSONSchema4 | string[]>;
397
  
398
  // Type validation
399
  /** Enumeration of valid values */
400
  enum?: JSONSchema4Type[];
401
  /** Expected type(s) */
402
  type?: JSONSchema4TypeName | JSONSchema4TypeName[];
403
  
404
  // String format
405
  /** String format specification */
406
  format?: string;
407
  
408
  // Schema composition
409
  /** All schemas must match */
410
  allOf?: JSONSchema4[];
411
  /** At least one schema must match */
412
  anyOf?: JSONSchema4[];
413
  /** Exactly one schema must match */
414
  oneOf?: JSONSchema4[];
415
  /** Schema must not match */
416
  not?: JSONSchema4;
417
}
418

419
/**
420
 * JSON Schema Draft 4 type names
421
 */
422
type JSONSchema4TypeName = 
423
  | 'string' 
424
  | 'number' 
425
  | 'integer' 
426
  | 'boolean' 
427
  | 'object' 
428
  | 'array' 
429
  | 'null' 
430
  | 'any';
431

432
/**
433
 * JSON Schema Draft 4 value types
434
 */
435
type JSONSchema4Type = 
436
  | string 
437
  | number 
438
  | boolean 
439
  | JSONSchema4Object 
440
  | JSONSchema4Array 
441
  | null;
442

443
/**
444
 * JSON Schema Draft 4 object type
445
 */
446
interface JSONSchema4Object {
447
  [key: string]: JSONSchema4Type;
448
}
449

450
/**
451
 * JSON Schema Draft 4 array type
452
 */
453
interface JSONSchema4Array extends Array<JSONSchema4Type> {}
454

455
/**
456
 * JSON Schema Draft 4 version identifier
457
 */
458
type JSONSchema4Version = 'http://json-schema.org/draft-04/schema#';
459
```
460

461
### Validation Types
462

463
Types for validation results and error reporting.
464

465
```typescript { .api }
466
/**
467
 * Validation result interface
468
 */
469
interface ValidationResult {
470
  /** Whether validation passed */
471
  valid: boolean;
472
  /** Validation errors (if any) */
473
  errors: ValidationError[];
474
  /** Instance being validated */
475
  instance: any;
476
  /** Schema used for validation */
477
  schema: JSONSchema7 | JSONSchema6 | JSONSchema4;
478
}
479

480
/**
481
 * Validation error interface
482
 */
483
interface ValidationError {
484
  /** Error message */
485
  message: string;
486
  /** Property path where error occurred */
487
  property: string;
488
  /** Instance path where error occurred */
489
  instance: string;
490
  /** Schema path that caused the error */
491
  schema: string;
492
  /** Stack trace (if available) */
493
  stack?: string;
494
  /** Error name */
495
  name: string;
496
  /** Validation error argument */
497
  argument?: any;
498
}
499
```
500

501
## Usage Examples
502

503
```typescript
504
import { JSONSchema, TSESLint } from "@typescript-eslint/experimental-utils";
505

506
// Define rule options schema
507
const ruleSchema: JSONSchema.JSONSchema7 = {
508
  type: 'object',
509
  properties: {
510
    ignorePatterns: {
511
      type: 'array',
512
      items: {
513
        type: 'string'
514
      },
515
      description: 'Patterns to ignore during analysis'
516
    },
517
    checkTypes: {
518
      type: 'boolean',
519
      default: true,
520
      description: 'Whether to perform type checking'
521
    },
522
    severity: {
523
      type: 'string',
524
      enum: ['error', 'warn', 'off'],
525
      default: 'error',
526
      description: 'Rule severity level'
527
    },
528
    maxComplexity: {
529
      type: 'integer',
530
      minimum: 1,
531
      maximum: 100,
532
      default: 10,
533
      description: 'Maximum allowed complexity'
534
    }
535
  },
536
  additionalProperties: false
537
};
538

539
// Use in a rule definition
540
const rule: TSESLint.RuleModule<'error', [typeof ruleSchema]> = {
541
  meta: {
542
    type: 'problem',
543
    messages: {
544
      error: 'Complexity too high: {{actual}} > {{max}}'
545
    },
546
    schema: [ruleSchema]
547
  },
548
  create(context, [options]) {
549
    // options is now type-safe based on the schema
550
    const ignorePatterns = options.ignorePatterns || [];
551
    const checkTypes = options.checkTypes ?? true;
552
    const severity = options.severity || 'error';
553
    const maxComplexity = options.maxComplexity || 10;
554
    
555
    return {
556
      // rule implementation
557
    };
558
  }
559
};
560

561
// Complex schema with conditional validation
562
const conditionalSchema: JSONSchema.JSONSchema7 = {
563
  type: 'object',
564
  properties: {
565
    mode: {
566
      type: 'string',
567
      enum: ['strict', 'loose']
568
    },
569
    options: {
570
      type: 'object'
571
    }
572
  },
573
  required: ['mode'],
574
  if: {
575
    properties: {
576
      mode: { const: 'strict' }
577
    }
578
  },
579
  then: {
580
    properties: {
581
      options: {
582
        type: 'object',
583
        properties: {
584
          enforceReturnType: {
585
            type: 'boolean',
586
            default: true
587
          },
588
          allowAny: {
589
            type: 'boolean',
590
            default: false
591
          }
592
        },
593
        required: ['enforceReturnType'],
594
        additionalProperties: false
595
      }
596
    }
597
  },
598
  else: {
599
    properties: {
600
      options: {
601
        type: 'object',
602
        properties: {
603
          skipPrivateMethods: {
604
            type: 'boolean',
605
            default: true
606
          }
607
        },
608
        additionalProperties: false
609
      }
610
    }
611
  }
612
};
613

614
// Schema with pattern properties
615
const patternSchema: JSONSchema.JSONSchema7 = {
616
  type: 'object',
617
  patternProperties: {
618
    '^[a-zA-Z][a-zA-Z0-9]*$': {
619
      type: 'object',
620
      properties: {
621
        enabled: { type: 'boolean' },
622
        priority: { type: 'integer', minimum: 0 }
623
      },
624
      required: ['enabled']
625
    }
626
  },
627
  additionalProperties: false
628
};
629

630
// Array schema with tuple validation
631
const tupleSchema: JSONSchema.JSONSchema7 = {
632
  type: 'array',
633
  items: [
634
    { type: 'string' },    // First item must be string
635
    { type: 'number' },    // Second item must be number
636
    { type: 'boolean' }    // Third item must be boolean
637
  ],
638
  additionalItems: false,  // No additional items allowed
639
  minItems: 2,            // At least first two items required
640
  maxItems: 3             // Maximum three items
641
};
642

643
// Schema composition example
644
const compositionSchema: JSONSchema.JSONSchema7 = {
645
  oneOf: [
646
    {
647
      type: 'string',
648
      pattern: '^[a-z]+$'
649
    },
650
    {
651
      type: 'object',
652
      properties: {
653
        name: { type: 'string' },
654
        enabled: { type: 'boolean' }
655
      },
656
      required: ['name'],
657
      additionalProperties: false
658
    },
659
    {
660
      type: 'array',
661
      items: { type: 'string' },
662
      minItems: 1
663
    }
664
  ]
665
};
666

667
// Using schema for validation in tests
668
function validateRuleOptions(options: unknown, schema: JSONSchema.JSONSchema7): boolean {
669
  // In a real implementation, you would use a JSON Schema validator library
670
  // This is a simplified example showing the type structure
671
  
672
  if (schema.type === 'object' && typeof options === 'object' && options !== null) {
673
    const obj = options as Record<string, unknown>;
674
    
675
    // Check required properties
676
    if (schema.required) {
677
      for (const prop of schema.required) {
678
        if (!(prop in obj)) {
679
          return false;
680
        }
681
      }
682
    }
683
    
684
    // Check property types
685
    if (schema.properties) {
686
      for (const [prop, propSchema] of Object.entries(schema.properties)) {
687
        if (prop in obj) {
688
          const value = obj[prop];
689
          if (typeof propSchema === 'object' && 'type' in propSchema) {
690
            if (propSchema.type === 'string' && typeof value !== 'string') {
691
              return false;
692
            }
693
            if (propSchema.type === 'boolean' && typeof value !== 'boolean') {
694
              return false;
695
            }
696
            if (propSchema.type === 'number' && typeof value !== 'number') {
697
              return false;
698
            }
699
          }
700
        }
701
      }
702
    }
703
    
704
    return true;
705
  }
706
  
707
  return false;
708
}
709

710
// Helper function to create type-safe rule schemas
711
function createRuleSchema<T extends Record<string, JSONSchema.JSONSchema7>>(
712
  properties: T
713
): JSONSchema.JSONSchema7 {
714
  return {
715
    type: 'object',
716
    properties,
717
    additionalProperties: false
718
  };
719
}
720

721
// Usage of helper
722
const myRuleSchema = createRuleSchema({
723
  checkImports: {
724
    type: 'boolean',
725
    default: true,
726
    description: 'Whether to check import statements'
727
  },
728
  allowedModules: {
729
    type: 'array',
730
    items: { type: 'string' },
731
    description: 'List of allowed module names'
732
  }
733
});
734

735
// Schema with format validation
736
const formatSchema: JSONSchema.JSONSchema7 = {
737
  type: 'object',
738
  properties: {
739
    email: {
740
      type: 'string',
741
      format: 'email'
742
    },
743
    url: {
744
      type: 'string',
745
      format: 'uri'
746
    },
747
    date: {
748
      type: 'string',
749
      format: 'date'
750
    },
751
    ipv4: {
752
      type: 'string',
753
      format: 'ipv4' 
754
    },
755
    regex: {
756
      type: 'string',
757
      format: 'regex'
758
    }
759
  }
760
};
761

762
// Schema with content validation
763
const contentSchema: JSONSchema.JSONSchema7 = {
764
  type: 'object',
765
  properties: {
766
    jsonData: {
767
      type: 'string',
768
      contentMediaType: 'application/json'
769
    },
770
    base64Data: {
771
      type: 'string',
772
      contentEncoding: 'base64'
773
    },
774
    htmlContent: {
775
      type: 'string',
776
      contentMediaType: 'text/html'
777
    }
778
  }
779
};
780
```
781

782
## Common Schema Patterns
783

784
```typescript { .api }
785
// Utility types for common schema patterns
786

787
/**
788
 * Schema for string with enumeration
789
 */
790
type StringEnumSchema<T extends readonly string[]> = {
791
  type: 'string';
792
  enum: T;
793
};
794

795
/**
796
 * Schema for optional boolean with default
797
 */
798
type BooleanWithDefaultSchema = {
799
  type: 'boolean';
800
  default: boolean;
801
};
802

803
/**
804
 * Schema for array of specific type
805
 */
806
type ArrayOfSchema<T extends JSONSchema.JSONSchema7> = {
807
  type: 'array';
808
  items: T;
809
};
810

811
/**
812
 * Schema for object with specific properties
813
 */
814
type ObjectWithPropertiesSchema<T extends Record<string, JSONSchema.JSONSchema7>> = {
815
  type: 'object';
816
  properties: T;
817
  additionalProperties: false;
818
};
819

820
/**
821
 * Schema for union types using oneOf
822
 */
823
type UnionSchema<T extends readonly JSONSchema.JSONSchema7[]> = {
824
  oneOf: T;
825
};
826

827
// Examples of utility usage
828
const colorSchema: StringEnumSchema<['red', 'green', 'blue']> = {
829
  type: 'string',
830
  enum: ['red', 'green', 'blue']
831
};
832

833
const enabledSchema: BooleanWithDefaultSchema = {
834
  type: 'boolean',
835
  default: false
836
};
837

838
const stringArraySchema: ArrayOfSchema<{ type: 'string' }> = {
839
  type: 'array',
840
  items: { type: 'string' }
841
};
842

843
const configSchema: ObjectWithPropertiesSchema<{
844
  name: { type: 'string' };
845
  version: { type: 'number' };
846
}> = {
847
  type: 'object',
848
  properties: {
849
    name: { type: 'string' },
850
    version: { type: 'number' }
851
  },
852
  additionalProperties: false
853
};
854

855
const mixedValueSchema: UnionSchema<[
856
  { type: 'string' },
857
  { type: 'number' },
858
  { type: 'boolean' }
859
]> = {
860
  oneOf: [
861
    { type: 'string' },
862
    { type: 'number' },
863
    { type: 'boolean' }
864
  ]
865
};
866
```