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
```