0
# Configuration and Customization
1

2
Advanced configuration options for customizing validation behavior, including schema loading, validation rules, library management, and message customization. The configuration system allows fine-grained control over how schemas are loaded, validated, and reported.
3

4
## Capabilities
5

6
### ValidationConfiguration
7

8
Central configuration for controlling validation behavior and rule sets.
9

10
```java { .api }
11
/**
12
 * Immutable configuration for validation behavior and library management
13
 */
14
public final class ValidationConfiguration {
15
    /**
16
     * Get default validation configuration
17
     * @return Default ValidationConfiguration instance
18
     */
19
    public static ValidationConfiguration byDefault();
20
    
21
    /**
22
     * Create new configuration builder
23
     * @return ValidationConfigurationBuilder for customization
24
     */
25
    public static ValidationConfigurationBuilder newBuilder();
26
    
27
    /**
28
     * Check if format validation is enabled
29
     * @return true if format attributes are validated
30
     */
31
    public boolean getUseFormat();
32
    
33
    /**
34
     * Get the default keyword library
35
     * @return Library containing default validation keywords
36
     */
37
    public Library getDefaultLibrary();
38
    
39
    /**
40
     * Get all configured libraries mapped by schema URI
41
     * @return Map of JsonRef to Library instances
42
     */
43
    public Map<JsonRef, Library> getLibraries();
44
    
45
    /**
46
     * Get message bundle for syntax error messages
47
     * @return MessageBundle for syntax validation messages
48
     */
49
    public MessageBundle getSyntaxMessages();
50
    
51
    /**
52
     * Get message bundle for validation error messages
53
     * @return MessageBundle for validation error messages
54
     */
55
    public MessageBundle getValidationMessages();
56
    
57
    /**
58
     * Create mutable copy for modification
59
     * @return ValidationConfigurationBuilder with current settings
60
     */
61
    public ValidationConfigurationBuilder thaw();
62
}
63
```
64

65
### ValidationConfigurationBuilder
66

67
Builder for creating customized validation configurations.
68

69
```java { .api }
70
/**
71
 * Builder for creating custom validation configurations
72
 */
73
public final class ValidationConfigurationBuilder {
74
    /**
75
     * Set the default JSON Schema version to use
76
     * @param version SchemaVersion (DRAFTV3 or DRAFTV4)
77
     * @return This builder for method chaining
78
     */
79
    public ValidationConfigurationBuilder setDefaultVersion(SchemaVersion version);
80
    
81
    /**
82
     * Set default library for validation keywords
83
     * @param uri Schema URI string
84
     * @param library Library instance to use as default
85
     * @return This builder for method chaining
86
     */
87
    public ValidationConfigurationBuilder setDefaultLibrary(String uri, Library library);
88
    
89
    /**
90
     * Add custom library for specific schema version
91
     * @param uri Schema URI string
92
     * @param library Library instance to register
93
     * @return This builder for method chaining
94
     */
95
    public ValidationConfigurationBuilder addLibrary(String uri, Library library);
96
    
97
    /**
98
     * Enable or disable format attribute validation
99
     * @param useFormat true to enable format validation
100
     * @return This builder for method chaining
101
     */
102
    public ValidationConfigurationBuilder setUseFormat(boolean useFormat);
103
    
104
    /**
105
     * Set custom message bundle for syntax errors
106
     * @param syntaxMessages MessageBundle for syntax error messages
107
     * @return This builder for method chaining
108
     */
109
    public ValidationConfigurationBuilder setSyntaxMessages(MessageBundle syntaxMessages);
110
    
111
    /**
112
     * Set custom message bundle for validation errors
113
     * @param validationMessages MessageBundle for validation error messages
114
     * @return This builder for method chaining
115
     */
116
    public ValidationConfigurationBuilder setValidationMessages(MessageBundle validationMessages);
117
    
118
    /**
119
     * Create immutable configuration instance
120
     * @return ValidationConfiguration with applied settings
121
     */
122
    public ValidationConfiguration freeze();
123
}
124
```
125

126
**Usage Examples:**
127

128
```java
129
import com.github.fge.jsonschema.cfg.ValidationConfiguration;
130
import com.github.fge.jsonschema.cfg.ValidationConfigurationBuilder;
131
import com.github.fge.jsonschema.library.DraftV4Library;
132
import com.github.fge.jsonschema.core.messages.JsonSchemaValidationBundle;
133

134
// Custom validation configuration
135
ValidationConfiguration config = ValidationConfiguration.newBuilder()
136
    .setDefaultVersion(SchemaVersion.DRAFTV4)
137
    .setUseFormat(false)  // Disable format validation for performance
138
    .addLibrary("http://json-schema.org/draft-04/schema#", DraftV4Library.get())
139
    .freeze();
140

141
// Use custom configuration with factory
142
JsonSchemaFactory factory = JsonSchemaFactory.newBuilder()
143
    .setValidationConfiguration(config)
144
    .freeze();
145

146
// Configuration with custom messages
147
MessageBundle customMessages = JsonSchemaValidationBundle.getInstance();
148
ValidationConfiguration msgConfig = ValidationConfiguration.newBuilder()
149
    .setSyntaxMessages(customMessages)
150
    .setValidationMessages(customMessages)
151
    .freeze();
152

153
// Modify existing configuration
154
ValidationConfiguration existing = ValidationConfiguration.byDefault();
155
ValidationConfiguration modified = existing.thaw()
156
    .setUseFormat(true)
157
    .freeze();
158
```
159

160
### LoadingConfiguration
161

162
Configuration for controlling how schemas are loaded and dereferenced.
163

164
```java { .api }
165
/**
166
 * Configuration for schema loading and URI resolution behavior
167
 */
168
public final class LoadingConfiguration {
169
    /**
170
     * Get default loading configuration
171
     * @return Default LoadingConfiguration instance
172
     */
173
    public static LoadingConfiguration byDefault();
174
    
175
    /**
176
     * Create new loading configuration builder
177
     * @return LoadingConfigurationBuilder for customization
178
     */
179
    public static LoadingConfigurationBuilder newBuilder();
180
    
181
    /**
182
     * Get URI translator configuration
183
     * @return URITranslatorConfiguration for URI handling
184
     */
185
    public URITranslatorConfiguration getTranslatorConfiguration();
186
    
187
    /**
188
     * Get dereferencing mode
189
     * @return Dereferencing mode (CANONICAL or INLINE)
190
     */
191
    public Dereferencing getDereferencing();
192
    
193
    /**
194
     * Get schema downloaders for different URI schemes
195
     * @return Map of scheme to URIDownloader instances
196
     */
197
    public Map<String, URIDownloader> getDownloaders();
198
    
199
    /**
200
     * Create mutable copy for modification
201
     * @return LoadingConfigurationBuilder with current settings
202
     */
203
    public LoadingConfigurationBuilder thaw();
204
}
205

206
/**
207
 * Builder for creating custom loading configurations
208
 */
209
public final class LoadingConfigurationBuilder {
210
    /**
211
     * Set dereferencing mode for JSON reference resolution
212
     * @param dereferencing Dereferencing mode (CANONICAL or INLINE)
213
     * @return This builder for method chaining
214
     */
215
    public LoadingConfigurationBuilder dereferencing(Dereferencing dereferencing);
216
    
217
    /**
218
     * Set URI translator configuration for namespace handling
219
     * @param translatorConfiguration URITranslatorConfiguration instance
220
     * @return This builder for method chaining
221
     */
222
    public LoadingConfigurationBuilder setURITranslatorConfiguration(URITranslatorConfiguration translatorConfiguration);
223
    
224
    /**
225
     * Add custom URI downloader for specific scheme
226
     * @param scheme URI scheme (http, https, file, etc.)
227
     * @param downloader URIDownloader implementation
228
     * @return This builder for method chaining
229
     */
230
    public LoadingConfigurationBuilder addScheme(String scheme, URIDownloader downloader);
231
    
232
    /**
233
     * Create immutable loading configuration
234
     * @return LoadingConfiguration with applied settings
235
     */
236
    public LoadingConfiguration freeze();
237
}
238
```
239

240
**Usage Examples:**
241

242
```java
243
import com.github.fge.jsonschema.core.load.Dereferencing;
244
import com.github.fge.jsonschema.core.load.configuration.LoadingConfiguration;
245
import com.github.fge.jsonschema.core.load.uri.URITranslatorConfiguration;
246

247
// Configure inline dereferencing for schemas with id-based references
248
LoadingConfiguration inlineConfig = LoadingConfiguration.newBuilder()
249
    .dereferencing(Dereferencing.INLINE)
250
    .freeze();
251

252
// Set up URI namespace for relative schema references
253
URITranslatorConfiguration uriConfig = URITranslatorConfiguration.newBuilder()
254
    .setNamespace("resource:/schemas/")
255
    .freeze();
256

257
LoadingConfiguration namespaceConfig = LoadingConfiguration.newBuilder()
258
    .setURITranslatorConfiguration(uriConfig)
259
    .freeze();
260

261
// Use with factory
262
JsonSchemaFactory factory = JsonSchemaFactory.newBuilder()
263
    .setLoadingConfiguration(inlineConfig)
264
    .freeze();
265

266
// Custom URI downloader for specific scheme
267
LoadingConfiguration customDownloadConfig = LoadingConfiguration.newBuilder()
268
    .addScheme("custom", new CustomURIDownloader())
269
    .freeze();
270
```
271

272
### SchemaVersion Enumeration
273

274
```java { .api }
275
/**
276
 * Supported JSON Schema specification versions
277
 */
278
public enum SchemaVersion {
279
    /**
280
     * JSON Schema Draft v3 specification
281
     */
282
    DRAFTV3("http://json-schema.org/draft-03/schema#"),
283
    
284
    /**
285
     * JSON Schema Draft v4 specification (default)
286
     */
287
    DRAFTV4("http://json-schema.org/draft-04/schema#");
288
    
289
    /**
290
     * Get the schema URI for this version
291
     * @return Schema URI string
292
     */
293
    public String getLocation();
294
}
295
```
296

297
### URITranslatorConfiguration
298

299
Configuration for URI translation and namespace handling.
300

301
```java { .api }
302
/**
303
 * Configuration for URI translation and namespace resolution
304
 */
305
public final class URITranslatorConfiguration {
306
    /**
307
     * Create new URI translator configuration builder
308
     * @return URITranslatorConfigurationBuilder for customization
309
     */
310
    public static URITranslatorConfigurationBuilder newBuilder();
311
    
312
    /**
313
     * Get the configured namespace URI
314
     * @return Namespace URI string or null if not set
315
     */
316
    public String getNamespace();
317
    
318
    /**
319
     * Get path redirections map
320
     * @return Map of path redirections
321
     */
322
    public Map<String, String> getPathRedirections();
323
}
324

325
/**
326
 * Builder for URI translator configuration
327
 */
328
public final class URITranslatorConfigurationBuilder {
329
    /**
330
     * Set namespace for relative URI resolution
331
     * @param namespace Base namespace URI
332
     * @return This builder for method chaining
333
     */
334
    public URITranslatorConfigurationBuilder setNamespace(String namespace);
335
    
336
    /**
337
     * Add path redirection mapping
338
     * @param from Source path pattern
339
     * @param to Target path pattern
340
     * @return This builder for method chaining
341
     */
342
    public URITranslatorConfigurationBuilder addPathRedirection(String from, String to);
343
    
344
    /**
345
     * Create immutable URI translator configuration
346
     * @return URITranslatorConfiguration with applied settings
347
     */
348
    public URITranslatorConfiguration freeze();
349
}
350
```
351

352
### Dereferencing Modes
353

354
```java { .api }
355
/**
356
 * JSON reference dereferencing modes
357
 */
358
public enum Dereferencing {
359
    /**
360
     * Canonical dereferencing using $ref resolution
361
     */
362
    CANONICAL,
363
    
364
    /**
365
     * Inline dereferencing using id-based resolution
366
     */
367
    INLINE;
368
}
369
```
370

371
## Complete Configuration Examples
372

373
### Example 1: Custom Validation with Disabled Format Validation
374
```java
375
// Create configuration that disables format validation for performance
376
ValidationConfiguration config = ValidationConfiguration.newBuilder()
377
    .setUseFormat(false)
378
    .setDefaultVersion(SchemaVersion.DRAFTV4)
379
    .freeze();
380

381
JsonSchemaFactory factory = JsonSchemaFactory.newBuilder()
382
    .setValidationConfiguration(config)
383
    .freeze();
384

385
JsonSchema schema = factory.getJsonSchema(schemaNode);
386
```
387

388
### Example 2: Schema Loading with Namespace
389
```java
390
// Set up namespace for loading schemas from a specific location
391
URITranslatorConfiguration uriConfig = URITranslatorConfiguration.newBuilder()
392
    .setNamespace("resource:/com/example/schemas/")
393
    .freeze();
394

395
LoadingConfiguration loadingConfig = LoadingConfiguration.newBuilder()
396
    .setURITranslatorConfiguration(uriConfig)
397
    .freeze();
398

399
JsonSchemaFactory factory = JsonSchemaFactory.newBuilder()
400
    .setLoadingConfiguration(loadingConfig)
401
    .freeze();
402

403
// Now can load schemas using relative URIs
404
JsonSchema schema = factory.getJsonSchema("user-schema.json");
405
```
406

407
### Example 3: Inline Dereferencing for ID-based Schemas
408
```java
409
// Configure for schemas that use "id" properties for inline references
410
LoadingConfiguration inlineConfig = LoadingConfiguration.newBuilder()
411
    .dereferencing(Dereferencing.INLINE)
412
    .freeze();
413

414
JsonSchemaFactory factory = JsonSchemaFactory.newBuilder()
415
    .setLoadingConfiguration(inlineConfig)
416
    .freeze();
417
```
418

419
### Example 4: Complete Custom Configuration
420
```java
421
// Comprehensive custom configuration
422
ValidationConfiguration validationConfig = ValidationConfiguration.newBuilder()
423
    .setDefaultVersion(SchemaVersion.DRAFTV4)
424
    .setUseFormat(true)
425
    .addLibrary("http://json-schema.org/draft-04/schema#", DraftV4Library.get())
426
    .freeze();
427

428
URITranslatorConfiguration uriConfig = URITranslatorConfiguration.newBuilder()
429
    .setNamespace("http://example.com/schemas/")
430
    .addPathRedirection("/old-path/", "/new-path/")
431
    .freeze();
432

433
LoadingConfiguration loadingConfig = LoadingConfiguration.newBuilder()
434
    .setURITranslatorConfiguration(uriConfig)
435
    .dereferencing(Dereferencing.CANONICAL)
436
    .freeze();
437

438
JsonSchemaFactory factory = JsonSchemaFactory.newBuilder()
439
    .setValidationConfiguration(validationConfig)
440
    .setLoadingConfiguration(loadingConfig)
441
    .freeze();
442
```
443

444
## Configuration Best Practices
445

446
1. **Performance**: Disable format validation with `setUseFormat(false)` if you don't need format checking
447
2. **Reusability**: Create factories with specific configurations and reuse them across your application
448
3. **Schema Organization**: Use namespaces to organize schemas in a logical directory structure
449
4. **Version Control**: Explicitly set schema versions to ensure consistent validation behavior
450
5. **Error Handling**: Configure custom message bundles for internationalization or application-specific error messages