0
# Basic Validation
1

2
Core schema validation functionality for validating JSON instances against JSON Schema definitions. Provides both single-use validation and reusable schema instances for efficient repeated validation.
3

4
## Capabilities
5

6
### JsonSchemaFactory
7

8
Main factory for creating validators and schema instances with default or custom configurations.
9

10
```java { .api }
11
/**
12
 * Main factory class for creating JSON Schema validators and schema instances
13
 */
14
public final class JsonSchemaFactory {
15
    /**
16
     * Get default factory instance with standard configuration
17
     * @return Default JsonSchemaFactory instance
18
     */
19
    public static JsonSchemaFactory byDefault();
20
    
21
    /**
22
     * Create a new factory builder for custom configuration
23
     * @return JsonSchemaFactoryBuilder for customization
24
     */
25
    public static JsonSchemaFactoryBuilder newBuilder();
26
    
27
    /**
28
     * Get a generic validator for one-off validations
29
     * @return JsonValidator instance
30
     */
31
    public JsonValidator getValidator();
32
    
33
    /**
34
     * Create a reusable schema instance from a JSON schema node
35
     * @param schema JsonNode containing the JSON schema
36
     * @return JsonSchema instance for validation
37
     * @throws ProcessingException if schema is invalid
38
     */
39
    public JsonSchema getJsonSchema(JsonNode schema) throws ProcessingException;
40
    
41
    /**
42
     * Create a schema instance from a JSON schema node with JSON Pointer
43
     * @param schema JsonNode containing the JSON schema
44
     * @param ptr JSON Pointer to specific schema location
45
     * @return JsonSchema instance for validation
46
     * @throws ProcessingException if schema is invalid or pointer is invalid
47
     */
48
    public JsonSchema getJsonSchema(JsonNode schema, String ptr) throws ProcessingException;
49
    
50
    /**
51
     * Load and create a schema instance from a URI
52
     * @param uri URI string pointing to the JSON schema
53
     * @return JsonSchema instance for validation
54
     * @throws ProcessingException if schema cannot be loaded or is invalid
55
     */
56
    public JsonSchema getJsonSchema(String uri) throws ProcessingException;
57
    
58
    /**
59
     * Get the raw validation processor for advanced usage
60
     * @return Processor for direct validation processing
61
     */
62
    public Processor<FullData, FullData> getProcessor();
63
    
64
    /**
65
     * Create a syntax validator for schema validation only
66
     * @return SyntaxValidator instance
67
     */
68
    public SyntaxValidator getSyntaxValidator();
69
    
70
    /**
71
     * Create a mutable copy of this factory for modification
72
     * @return JsonSchemaFactoryBuilder with current settings
73
     */
74
    public JsonSchemaFactoryBuilder thaw();
75
}
76
```
77

78
**Usage Examples:**
79

80
```java
81
import com.fasterxml.jackson.databind.JsonNode;
82
import com.fasterxml.jackson.databind.ObjectMapper;
83
import com.github.fge.jsonschema.main.JsonSchemaFactory;
84
import com.github.fge.jsonschema.main.JsonSchema;
85

86
// Create factory with default settings
87
JsonSchemaFactory factory = JsonSchemaFactory.byDefault();
88

89
// Load schema from JsonNode
90
ObjectMapper mapper = new ObjectMapper();
91
JsonNode schemaNode = mapper.readTree("{\n" +
92
    "  \"type\": \"object\",\n" +
93
    "  \"properties\": {\n" +
94
    "    \"name\": { \"type\": \"string\" },\n" +
95
    "    \"age\": { \"type\": \"integer\", \"minimum\": 0 }\n" +
96
    "  },\n" +
97
    "  \"required\": [\"name\"]\n" +
98
    "}");
99

100
JsonSchema schema = factory.getJsonSchema(schemaNode);
101

102
// Load schema from URI
103
JsonSchema uriSchema = factory.getJsonSchema("http://json-schema.org/draft-04/schema#");
104

105
// Use JSON Pointer to reference subschema
106
JsonNode complexSchema = mapper.readTree("{\n" +
107
    "  \"definitions\": {\n" +
108
    "    \"person\": {\n" +
109
    "      \"type\": \"object\",\n" +
110
    "      \"properties\": { \"name\": { \"type\": \"string\" } }\n" +
111
    "    }\n" +
112
    "  }\n" +
113
    "}");
114
JsonSchema subSchema = factory.getJsonSchema(complexSchema, "#/definitions/person");
115
```
116

117
### JsonSchema
118

119
Reusable validator instance for a specific schema, optimized for repeated validation operations.
120

121
```java { .api }
122
/**
123
 * Single-schema validator for efficient repeated validation
124
 */
125
public final class JsonSchema {
126
    /**
127
     * Validate a JSON instance against this schema
128
     * @param instance JsonNode to validate
129
     * @return ProcessingReport containing validation results
130
     * @throws ProcessingException if validation processing fails
131
     */
132
    public ProcessingReport validate(JsonNode instance) throws ProcessingException;
133
    
134
    /**
135
     * Validate with deep checking enabled for thorough validation
136
     * @param instance JsonNode to validate
137
     * @param deepCheck Enable deep validation checking
138
     * @return ProcessingReport containing validation results
139
     * @throws ProcessingException if validation processing fails
140
     */
141
    public ProcessingReport validate(JsonNode instance, boolean deepCheck) throws ProcessingException;
142
    
143
    /**
144
     * Validate without throwing exceptions on validation failure
145
     * @param instance JsonNode to validate
146
     * @return ProcessingReport containing validation results
147
     */
148
    public ProcessingReport validateUnchecked(JsonNode instance);
149
    
150
    /**
151
     * Validate unchecked with deep checking option
152
     * @param instance JsonNode to validate
153
     * @param deepCheck Enable deep validation checking
154
     * @return ProcessingReport containing validation results
155
     */
156
    public ProcessingReport validateUnchecked(JsonNode instance, boolean deepCheck);
157
    
158
    /**
159
     * Simple boolean check if instance is valid
160
     * @param instance JsonNode to validate
161
     * @return true if valid, false otherwise
162
     * @throws ProcessingException if validation processing fails
163
     */
164
    public boolean validInstance(JsonNode instance) throws ProcessingException;
165
    
166
    /**
167
     * Simple boolean check without throwing exceptions
168
     * @param instance JsonNode to validate
169
     * @return true if valid, false otherwise
170
     */
171
    public boolean validInstanceUnchecked(JsonNode instance);
172
}
173
```
174

175
**Usage Examples:**
176

177
```java
178
import com.fasterxml.jackson.databind.JsonNode;
179
import com.fasterxml.jackson.databind.ObjectMapper;
180
import com.github.fge.jsonschema.core.report.ProcessingReport;
181

182
// Reusable schema validation
183
JsonSchema schema = factory.getJsonSchema(schemaNode);
184
ObjectMapper mapper = new ObjectMapper();
185

186
// Validate multiple instances
187
JsonNode validData = mapper.readTree("{\"name\": \"John\", \"age\": 30}");
188
JsonNode invalidData = mapper.readTree("{\"age\": \"not-a-number\"}");
189

190
// Full validation with detailed report
191
ProcessingReport report1 = schema.validate(validData);
192
System.out.println("Valid: " + report1.isSuccess());
193

194
ProcessingReport report2 = schema.validate(invalidData);
195
if (!report2.isSuccess()) {
196
    for (ProcessingMessage message : report2) {
197
        System.out.println("Error: " + message.getMessage());
198
    }
199
}
200

201
// Simple boolean validation
202
boolean isValid1 = schema.validInstance(validData);  // true
203
boolean isValid2 = schema.validInstance(invalidData); // false
204

205
// Unchecked validation (no exceptions)
206
ProcessingReport uncheckedReport = schema.validateUnchecked(invalidData);
207
boolean uncheckedValid = schema.validInstanceUnchecked(invalidData);
208

209
// Deep validation for comprehensive checking
210
ProcessingReport deepReport = schema.validate(validData, true);
211
```
212

213
### JsonValidator
214

215
Generic validator for one-off validations where you don't need to reuse the schema instance.
216

217
```java { .api }
218
/**
219
 * Generic validator for one-time schema/instance validation pairs
220
 */
221
public final class JsonValidator {
222
    /**
223
     * Validate instance against schema
224
     * @param schema JsonNode containing the JSON schema
225
     * @param instance JsonNode to validate
226
     * @return ProcessingReport containing validation results
227
     * @throws ProcessingException if validation processing fails
228
     */
229
    public ProcessingReport validate(JsonNode schema, JsonNode instance) throws ProcessingException;
230
    
231
    /**
232
     * Validate with deep checking enabled
233
     * @param schema JsonNode containing the JSON schema
234
     * @param instance JsonNode to validate
235
     * @param deepCheck Enable deep validation checking
236
     * @return ProcessingReport containing validation results
237
     * @throws ProcessingException if validation processing fails
238
     */
239
    public ProcessingReport validate(JsonNode schema, JsonNode instance, boolean deepCheck) throws ProcessingException;
240
    
241
    /**
242
     * Validate without throwing exceptions on validation failure
243
     * @param schema JsonNode containing the JSON schema
244
     * @param instance JsonNode to validate
245
     * @return ProcessingReport containing validation results
246
     */
247
    public ProcessingReport validateUnchecked(JsonNode schema, JsonNode instance);
248
    
249
    /**
250
     * Validate unchecked with deep checking option
251
     * @param schema JsonNode containing the JSON schema
252
     * @param instance JsonNode to validate
253
     * @param deepCheck Enable deep validation checking
254
     * @return ProcessingReport containing validation results
255
     */
256
    public ProcessingReport validateUnchecked(JsonNode schema, JsonNode instance, boolean deepCheck);
257
}
258
```
259

260
**Usage Examples:**
261

262
```java
263
import com.github.fge.jsonschema.main.JsonValidator;
264

265
// One-off validation without creating schema instance
266
JsonValidator validator = factory.getValidator();
267

268
// Validate schema/instance pairs directly
269
ProcessingReport result = validator.validate(schemaNode, instanceNode);
270
if (result.isSuccess()) {
271
    System.out.println("Validation passed");
272
} else {
273
    System.out.println("Validation failed:");
274
    for (ProcessingMessage msg : result) {
275
        System.out.println("  " + msg.getMessage());
276
    }
277
}
278

279
// Unchecked validation for graceful error handling
280
ProcessingReport uncheckedResult = validator.validateUnchecked(schemaNode, instanceNode);
281
boolean success = uncheckedResult.isSuccess();
282

283
// Deep validation for thorough checking
284
ProcessingReport deepResult = validator.validate(schemaNode, instanceNode, true);
285
```
286

287
### JsonSchemaFactoryBuilder
288

289
Builder for creating customized factory instances with specific configurations.
290

291
```java { .api }
292
/**
293
 * Builder for customizing JsonSchemaFactory configuration
294
 */
295
public final class JsonSchemaFactoryBuilder {
296
    /**
297
     * Set custom loading configuration for schema loading behavior
298
     * @param loadingCfg LoadingConfiguration instance
299
     * @return This builder for method chaining
300
     */
301
    public JsonSchemaFactoryBuilder setLoadingConfiguration(LoadingConfiguration loadingCfg);
302
    
303
    /**
304
     * Set validation configuration for validation behavior
305
     * @param validationCfg ValidationConfiguration instance
306
     * @return This builder for method chaining
307
     */
308
    public JsonSchemaFactoryBuilder setValidationConfiguration(ValidationConfiguration validationCfg);
309
    
310
    /**
311
     * Set custom report provider for validation reporting
312
     * @param reportProvider ReportProvider instance
313
     * @return This builder for method chaining
314
     */
315
    public JsonSchemaFactoryBuilder setReportProvider(ReportProvider reportProvider);
316
    
317
    /**
318
     * Create immutable factory instance with configured settings
319
     * @return JsonSchemaFactory with applied configuration
320
     */
321
    public JsonSchemaFactory freeze();
322
}
323
```
324

325
**Usage Examples:**
326

327
```java
328
import com.github.fge.jsonschema.cfg.ValidationConfiguration;
329
import com.github.fge.jsonschema.core.load.configuration.LoadingConfiguration;
330

331
// Create custom factory with validation configuration
332
ValidationConfiguration validationCfg = ValidationConfiguration.newBuilder()
333
    .setUseFormat(false)  // Disable format validation
334
    .freeze();
335

336
JsonSchemaFactory customFactory = JsonSchemaFactory.newBuilder()
337
    .setValidationConfiguration(validationCfg)
338
    .freeze();
339

340
// Custom loading configuration
341
LoadingConfiguration loadingCfg = LoadingConfiguration.newBuilder()
342
    .dereferencing(Dereferencing.INLINE)
343
    .freeze();
344

345
JsonSchemaFactory factoryWithLoading = JsonSchemaFactory.newBuilder()
346
    .setLoadingConfiguration(loadingCfg)
347
    .setValidationConfiguration(validationCfg)
348
    .freeze();
349
```
350

351
## Common Usage Patterns
352

353
### Pattern 1: Reusable Schema Validation
354
```java
355
// Best for validating multiple instances against the same schema
356
JsonSchemaFactory factory = JsonSchemaFactory.byDefault();
357
JsonSchema schema = factory.getJsonSchema(schemaNode);
358

359
for (JsonNode instance : instances) {
360
    ProcessingReport report = schema.validate(instance);
361
    if (!report.isSuccess()) {
362
        // Handle validation failure
363
    }
364
}
365
```
366

367
### Pattern 2: One-off Validation
368
```java
369
// Best for single validations or different schemas each time
370
JsonValidator validator = JsonSchemaFactory.byDefault().getValidator();
371
ProcessingReport report = validator.validate(schemaNode, instanceNode);
372
```
373

374
### Pattern 3: Boolean Validation
375
```java
376
// When you only need pass/fail result
377
JsonSchema schema = factory.getJsonSchema(schemaNode);
378
boolean isValid = schema.validInstance(instanceNode);
379
```
380

381
### Pattern 4: Error-Safe Validation
382
```java
383
// When you want to avoid exceptions during validation
384
JsonSchema schema = factory.getJsonSchema(schemaNode);
385
ProcessingReport report = schema.validateUnchecked(instanceNode);
386
if (!report.isSuccess()) {
387
    // Process validation errors without exception handling
388
}
389
```