0
# JSON Schema Validator
1

2
JSON Schema Validator is a Hamcrest matcher library for validating JSON documents against JSON schemas, designed for use with REST Assured testing framework. It provides comprehensive JSON schema validation capabilities with configurable settings and factory support for Java-based testing environments.
3

4
## Package Information
5

6
- **Package Name**: json-schema-validator
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Group ID**: io.rest-assured
10
- **Artifact ID**: json-schema-validator
11
- **Installation**: Add to your Maven dependencies:
12
  ```xml
13
  <dependency>
14
    <groupId>io.rest-assured</groupId>
15
    <artifactId>json-schema-validator</artifactId>
16
    <version>5.5.2</version>
17
  </dependency>
18
  ```
19

20
## Core Imports
21

22
```java
23
import static io.restassured.module.jsv.JsonSchemaValidator.*;
24
import io.restassured.module.jsv.JsonSchemaValidator;
25
import io.restassured.module.jsv.JsonSchemaValidatorSettings;
26
import io.restassured.module.jsv.JsonSchemaValidationException;
27
```
28

29
## Basic Usage
30

31
```java
32
import static io.restassured.module.jsv.JsonSchemaValidator.*;
33
import static io.restassured.module.jsv.JsonSchemaValidatorSettings.*;
34
import static org.hamcrest.MatcherAssert.assertThat;
35

36
// Validate JSON against schema in classpath
37
String jsonResponse = "{ \"name\": \"John\", \"age\": 30 }";
38
assertThat(jsonResponse, matchesJsonSchemaInClasspath("user-schema.json"));
39

40
// Validate with custom settings
41
assertThat(jsonResponse, 
42
    matchesJsonSchemaInClasspath("user-schema.json")
43
        .using(settings().with().checkedValidation(false)));
44

45
// Configure static settings for all validations
46
JsonSchemaValidator.settings = settings().with().checkedValidation(false);
47
assertThat(jsonResponse, matchesJsonSchemaInClasspath("user-schema.json"));
48
```
49

50
## Architecture
51

52
JSON Schema Validator is built around several key components:
53

54
- **JsonSchemaValidator**: Main Hamcrest matcher class extending TypeSafeMatcher<String>
55
- **JsonSchemaValidatorSettings**: Configuration class for customizing validation behavior
56
- **Static Configuration**: Global settings that apply to all validator instances
57
- **Multiple Schema Sources**: Support for classpath, file, URL, URI, String, and Stream schema sources
58
- **Hamcrest Integration**: Full compatibility with Hamcrest matcher ecosystem
59

60
## Capabilities
61

62
### Schema Validation from Multiple Sources
63

64
Core JSON schema validation functionality supporting various schema source types. Perfect for REST API testing and JSON document validation.
65

66
```java { .api }
67
/**
68
 * Creates a Hamcrest matcher that validates JSON documents against schemas from various sources
69
 */
70
public static JsonSchemaValidator matchesJsonSchema(String schema);
71
public static JsonSchemaValidator matchesJsonSchemaInClasspath(String pathToSchemaInClasspath);
72
public static JsonSchemaValidator matchesJsonSchema(InputStream schema);
73
public static JsonSchemaValidator matchesJsonSchema(Reader schema);
74
public static JsonSchemaValidator matchesJsonSchema(File file);
75
public static JsonSchemaValidator matchesJsonSchema(URL url);
76
public static JsonSchemaValidator matchesJsonSchema(URI uri);
77
```
78

79
**Usage Examples:**
80

81
```java
82
// String schema
83
String schemaString = "{ \"type\": \"object\", \"properties\": { \"name\": { \"type\": \"string\" } } }";
84
assertThat(jsonData, matchesJsonSchema(schemaString));
85

86
// Classpath resource
87
assertThat(jsonData, matchesJsonSchemaInClasspath("schemas/user.json"));
88

89
// File
90
File schemaFile = new File("path/to/schema.json");
91
assertThat(jsonData, matchesJsonSchema(schemaFile));
92

93
// URL
94
URL schemaUrl = new URL("https://example.com/schema.json");
95
assertThat(jsonData, matchesJsonSchema(schemaUrl));
96

97
// URI
98
URI schemaUri = URI.create("file:///path/to/schema.json");
99
assertThat(jsonData, matchesJsonSchema(schemaUri));
100
```
101

102
### Custom Validation Configuration
103

104
Configure validation behavior using JsonSchemaFactory or JsonSchemaValidatorSettings for advanced validation scenarios.
105

106
```java { .api }
107
/**
108
 * Configure the validator with custom factory or settings
109
 */
110
public Matcher<?> using(JsonSchemaFactory jsonSchemaFactory);
111
public Matcher<?> using(JsonSchemaValidatorSettings jsonSchemaValidatorSettings);
112
```
113

114
**Usage Examples:**
115

116
```java
117
import com.github.fge.jsonschema.main.JsonSchemaFactory;
118
import com.github.fge.jsonschema.cfg.ValidationConfiguration;
119
import static com.github.fge.jsonschema.SchemaVersion.DRAFTV4;
120

121
// Custom JsonSchemaFactory
122
JsonSchemaFactory factory = JsonSchemaFactory.newBuilder()
123
    .setValidationConfiguration(
124
        ValidationConfiguration.newBuilder()
125
            .setDefaultVersion(DRAFTV4)
126
            .freeze()
127
    )
128
    .freeze();
129
assertThat(jsonData, matchesJsonSchemaInClasspath("schema.json").using(factory));
130

131
// Custom settings
132
assertThat(jsonData, 
133
    matchesJsonSchemaInClasspath("schema.json")
134
        .using(settings().with().checkedValidation(false)));
135
```
136

137
### Static Configuration Management
138

139
Global configuration that applies to all validator instances, with reset capability for testing isolation.
140

141
```java { .api }
142
/**
143
 * Static configuration field and reset method
144
 */
145
public static JsonSchemaValidatorSettings settings;
146

147
/**
148
 * Reset the static settings to null
149
 */
150
public static void reset();
151
```
152

153
**Usage Examples:**
154

155
```java
156
// Set global configuration
157
JsonSchemaValidator.settings = settings().with().checkedValidation(false);
158

159
// All subsequent validations use unchecked validation
160
assertThat(jsonData1, matchesJsonSchemaInClasspath("schema1.json"));
161
assertThat(jsonData2, matchesJsonSchemaInClasspath("schema2.json"));
162

163
// Reset to default state
164
JsonSchemaValidator.reset();
165
assertThat(jsonData3, matchesJsonSchemaInClasspath("schema3.json")); // Uses default settings
166
```
167

168
### Validation Settings Configuration
169

170
Comprehensive configuration options for customizing validation behavior, JSON schema factory, and URI handling.
171

172
```java { .api }
173
/**
174
 * Configuration class for JSON schema validation settings
175
 */
176
public class JsonSchemaValidatorSettings {
177
    public JsonSchemaValidatorSettings();
178
    public JsonSchemaValidatorSettings(JsonSchemaFactory jsonSchemaFactory);
179
    public JsonSchemaValidatorSettings(JsonSchemaFactory jsonSchemaFactory, boolean checkedValidation);
180
    
181
    /**
182
     * Static factory method for creating default settings
183
     */
184
    public static JsonSchemaValidatorSettings settings();
185
    
186
    /**
187
     * Configuration methods returning new instances (immutable pattern)
188
     */
189
    public JsonSchemaValidatorSettings checkedValidation(boolean shouldUseCheckedValidation);
190
    public JsonSchemaValidatorSettings parseUriAndUrlsAsJsonNode(boolean parseUriAndUrlsAsJsonNode);
191
    public JsonSchemaValidatorSettings jsonSchemaFactory(JsonSchemaFactory jsonSchemaFactory);
192
    
193
    /**
194
     * Fluent API methods for method chaining
195
     */
196
    public JsonSchemaValidatorSettings and();
197
    public JsonSchemaValidatorSettings with();
198
    
199
    /**
200
     * Query methods for current configuration
201
     */
202
    public JsonSchemaFactory jsonSchemaFactory();
203
    public boolean shouldParseUriAndUrlsAsJsonNode();
204
    public boolean shouldUseCheckedValidation();
205
}
206
```
207

208
**Usage Examples:**
209

210
```java
211
// Create settings with different configurations
212
JsonSchemaValidatorSettings defaultSettings = settings();
213
JsonSchemaValidatorSettings uncheckedSettings = settings().with().checkedValidation(false);
214
JsonSchemaValidatorSettings customSettings = settings()
215
    .with()
216
    .checkedValidation(false)
217
    .and()
218
    .parseUriAndUrlsAsJsonNode(true);
219

220
// Custom factory settings
221
JsonSchemaFactory customFactory = JsonSchemaFactory.byDefault();
222
JsonSchemaValidatorSettings factorySettings = settings().with().jsonSchemaFactory(customFactory);
223
```
224

225
### Exception Handling
226

227
Runtime exception thrown when JSON schema validation encounters errors during processing.
228

229
```java { .api }
230
/**
231
 * Exception thrown when something goes wrong during JSON Schema validation
232
 */
233
public class JsonSchemaValidationException extends RuntimeException {
234
    public JsonSchemaValidationException(Throwable cause);
235
}
236
```
237

238
**Usage Examples:**
239

240
```java
241
try {
242
    assertThat(invalidJsonData, matchesJsonSchemaInClasspath("schema.json"));
243
} catch (JsonSchemaValidationException e) {
244
    // Handle validation processing errors
245
    System.out.println("Schema validation failed: " + e.getCause().getMessage());
246
}
247
```
248

249
## Types
250

251
```java { .api }
252
/**
253
 * Main validator class extending Hamcrest TypeSafeMatcher
254
 */
255
public class JsonSchemaValidator extends TypeSafeMatcher<String> {
256
    /**
257
     * Static configuration field for global settings
258
     */
259
    public static JsonSchemaValidatorSettings settings;
260
}
261

262
/**
263
 * Settings configuration class
264
 */
265
public class JsonSchemaValidatorSettings {
266
    // Constructor and method definitions shown in capabilities above
267
}
268

269
/**
270
 * Runtime exception for validation errors
271
 */
272
public class JsonSchemaValidationException extends RuntimeException {
273
    public JsonSchemaValidationException(Throwable cause);
274
}
275
```
276

277
## Error Handling
278

279
The library throws `JsonSchemaValidationException` when:
280
- Schema loading fails (malformed schema, file not found, network issues)
281
- JSON parsing fails (invalid JSON structure)
282
- Internal validation engine errors occur
283

284
Validation failures (JSON doesn't match schema) are handled through the Hamcrest matcher framework and result in assertion failures rather than exceptions.
285

286
## Dependencies
287

288
The library requires:
289
- **Hamcrest**: For matcher framework integration
290
- **Jackson**: For JSON parsing (JsonNode)
291
- **java-json-tools**: For JSON schema validation engine
292
- **Guava**: For internal collection utilities