0
# JSON Schema Validator
1
2
JSON Schema Validator is a comprehensive Java implementation of the JSON Schema specification supporting both draft v4 and v3 (with hyperschema syntax support for v4). It provides complete validation capabilities for JSON documents against JSON Schema definitions, includes command-line interface functionality, supports Android development environments, and offers extensive configuration options for validation behavior.
3
4
## Package Information
5
6
- **Package Name**: com.github.fge:json-schema-validator
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to Maven dependencies:
10
```xml
11
<dependency>
12
<groupId>com.github.fge</groupId>
13
<artifactId>json-schema-validator</artifactId>
14
<version>2.2.6</version>
15
</dependency>
16
```
17
- **Gradle**: `implementation 'com.github.fge:json-schema-validator:2.2.6'`
18
19
## Core Imports
20
21
```java
22
import com.github.fge.jsonschema.main.JsonSchemaFactory;
23
import com.github.fge.jsonschema.main.JsonSchema;
24
import com.github.fge.jsonschema.main.JsonValidator;
25
import com.github.fge.jsonschema.core.report.ProcessingReport;
26
import com.fasterxml.jackson.databind.JsonNode;
27
```
28
29
## Basic Usage
30
31
```java
32
import com.fasterxml.jackson.databind.JsonNode;
33
import com.github.fge.jsonschema.core.exceptions.ProcessingException;
34
import com.github.fge.jsonschema.core.report.ProcessingReport;
35
import com.github.fge.jsonschema.main.JsonSchema;
36
import com.github.fge.jsonschema.main.JsonSchemaFactory;
37
38
// Basic validation using default factory
39
JsonSchemaFactory factory = JsonSchemaFactory.byDefault();
40
JsonSchema schema = factory.getJsonSchema(schemaNode);
41
ProcessingReport report = schema.validate(instanceNode);
42
43
// Check if validation passed
44
boolean isValid = report.isSuccess();
45
if (!isValid) {
46
System.out.println("Validation failed: " + report);
47
}
48
49
// One-off validation without creating schema instance
50
JsonValidator validator = factory.getValidator();
51
ProcessingReport result = validator.validate(schemaNode, instanceNode);
52
```
53
54
## Architecture
55
56
JSON Schema Validator is built around several key components:
57
58
- **Factory Pattern**: `JsonSchemaFactory` serves as the main entry point for creating validators and schemas
59
- **Schema Objects**: `JsonSchema` provides reusable validation instances for specific schemas
60
- **Validation Engine**: Configurable processors handle the validation logic with support for different JSON Schema versions
61
- **Configuration System**: Extensive customization through `ValidationConfiguration` and `LoadingConfiguration`
62
- **Library System**: Modular keyword and format validation through pluggable `Library` components
63
- **Report System**: Detailed validation results with structured error reporting via `ProcessingReport`
64
65
## Capabilities
66
67
### Basic Validation
68
69
Core schema validation functionality for validating JSON instances against JSON Schema definitions. Supports both single-use and reusable validation patterns.
70
71
```java { .api }
72
public final class JsonSchemaFactory {
73
public static JsonSchemaFactory byDefault();
74
public static JsonSchemaFactoryBuilder newBuilder();
75
public JsonValidator getValidator();
76
public SyntaxValidator getSyntaxValidator();
77
public JsonSchema getJsonSchema(JsonNode schema) throws ProcessingException;
78
public JsonSchema getJsonSchema(JsonNode schema, String ptr) throws ProcessingException;
79
public JsonSchema getJsonSchema(String uri) throws ProcessingException;
80
public Processor<FullData, FullData> getProcessor();
81
}
82
83
public final class JsonSchema {
84
public ProcessingReport validate(JsonNode instance) throws ProcessingException;
85
public ProcessingReport validate(JsonNode instance, boolean deepCheck) throws ProcessingException;
86
public ProcessingReport validateUnchecked(JsonNode instance);
87
public ProcessingReport validateUnchecked(JsonNode instance, boolean deepCheck);
88
public boolean validInstance(JsonNode instance) throws ProcessingException;
89
public boolean validInstanceUnchecked(JsonNode instance);
90
}
91
92
public final class JsonValidator {
93
public ProcessingReport validate(JsonNode schema, JsonNode instance) throws ProcessingException;
94
public ProcessingReport validate(JsonNode schema, JsonNode instance, boolean deepCheck) throws ProcessingException;
95
public ProcessingReport validateUnchecked(JsonNode schema, JsonNode instance);
96
public ProcessingReport validateUnchecked(JsonNode schema, JsonNode instance, boolean deepCheck);
97
}
98
```
99
100
[Basic Validation](./basic-validation.md)
101
102
### Configuration and Customization
103
104
Advanced configuration options for customizing validation behavior, including schema loading, validation rules, and library management.
105
106
```java { .api }
107
public final class ValidationConfiguration {
108
public static ValidationConfiguration byDefault();
109
public static ValidationConfigurationBuilder newBuilder();
110
public boolean getUseFormat();
111
public Library getDefaultLibrary();
112
public Map<JsonRef, Library> getLibraries();
113
public MessageBundle getSyntaxMessages();
114
public MessageBundle getValidationMessages();
115
}
116
117
public final class ValidationConfigurationBuilder {
118
public ValidationConfigurationBuilder setDefaultVersion(SchemaVersion version);
119
public ValidationConfigurationBuilder setUseFormat(boolean useFormat);
120
public ValidationConfigurationBuilder addLibrary(String uri, Library library);
121
public ValidationConfigurationBuilder setDefaultLibrary(String uri, Library library);
122
public ValidationConfigurationBuilder setSyntaxMessages(MessageBundle syntaxMessages);
123
public ValidationConfigurationBuilder setValidationMessages(MessageBundle validationMessages);
124
public ValidationConfiguration freeze();
125
}
126
```
127
128
[Configuration and Customization](./configuration.md)
129
130
### Custom Keywords and Extensions
131
132
Extensibility system for adding custom validation keywords, format attributes, and validation logic through the library system.
133
134
```java { .api }
135
public final class Library {
136
public static LibraryBuilder newBuilder();
137
public Dictionary<SyntaxChecker> getSyntaxCheckers();
138
public Dictionary<Digester> getDigesters();
139
public Dictionary<Constructor<? extends KeywordValidator>> getValidators();
140
public Dictionary<FormatAttribute> getFormatAttributes();
141
}
142
143
public final class Keyword {
144
public static KeywordBuilder newBuilder(String name);
145
}
146
147
public interface KeywordValidator {
148
void validate(Processor<FullData, FullData> processor, ProcessingReport report,
149
MessageBundle bundle, FullData data) throws ProcessingException;
150
}
151
```
152
153
[Custom Keywords and Extensions](./extensions.md)
154
155
### Syntax Validation
156
157
Dedicated functionality for validating JSON Schema syntax without performing instance validation.
158
159
```java { .api }
160
public final class SyntaxValidator {
161
public boolean schemaIsValid(JsonNode schema);
162
public ProcessingReport validateSchema(JsonNode schema);
163
public Processor<ValueHolder<SchemaTree>, ValueHolder<SchemaTree>> getProcessor();
164
}
165
```
166
167
[Syntax Validation](./syntax-validation.md)
168
169
### Format Validation
170
171
Built-in format attribute validation for common data formats like email, URI, datetime, and extensible format validation system.
172
173
```java { .api }
174
public interface FormatAttribute {
175
EnumSet<NodeType> supportedTypes();
176
void validate(ProcessingReport report, MessageBundle bundle, FullData data)
177
throws ProcessingException;
178
}
179
```
180
181
[Format Validation](./format-validation.md)
182
183
### Command Line Interface
184
185
Command-line tools for JSON Schema validation from the command line with various output formats and options.
186
187
```java { .api }
188
public final class Main {
189
public static void main(String... args);
190
}
191
192
public enum RetCode {
193
OK, SCHEMA_SYNTAX_ERROR, VALIDATION_FAILURE, CMD_LINE_ERROR
194
}
195
```
196
197
[Command Line Interface](./cli.md)
198
199
## Exception Classes
200
201
```java { .api }
202
public class ProcessingException extends Exception {
203
public ProcessingException(ProcessingMessage message);
204
public ProcessingException(ProcessingMessage message, Throwable cause);
205
}
206
207
public class InvalidInstanceException extends ProcessingException {
208
public InvalidInstanceException(ProcessingMessage message);
209
}
210
```
211
212
## Types
213
214
```java { .api }
215
public interface ProcessingReport extends Iterable<ProcessingMessage> {
216
boolean isSuccess();
217
LogLevel getLogLevel();
218
ProcessingMessage getMessage();
219
}
220
221
public final class ProcessingMessage {
222
public String getMessage();
223
public LogLevel getLevel();
224
public JsonNode asJson();
225
}
226
227
public enum SchemaVersion {
228
DRAFTV3("http://json-schema.org/draft-03/schema#"),
229
DRAFTV4("http://json-schema.org/draft-04/schema#");
230
}
231
232
public enum NodeType {
233
ARRAY, BOOLEAN, INTEGER, NULL, NUMBER, OBJECT, STRING
234
}
235
236
public interface Processor<I, O> {
237
// Core processor interface for validation chains
238
}
239
240
public final class FullData {
241
// Complete data structure containing schema and instance information
242
}
243
244
public final class ValueHolder<T> {
245
// Generic value holder for processor chains
246
}
247
248
public final class SchemaTree {
249
// Immutable schema tree representation
250
}
251
252
public interface MessageBundle {
253
// Internationalized message bundle interface
254
}
255
256
public final class JsonRef {
257
// JSON Reference implementation
258
}
259
260
public interface Dictionary<T> {
261
// Generic dictionary interface for keyword collections
262
}
263
264
public enum LogLevel {
265
DEBUG, INFO, WARNING, ERROR, FATAL
266
}
267
```