You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This is a Java implementation of the [JSON Schema Core Draft v4, v6, v7, v2019-09 and v2020-12(partial)](http://json-schema.org/latest/json-schema-core.html) specification for JSON schema validation. In addition, it also works for OpenAPI 3.0 request/response validation with some [configuration flags](doc/config.md). For users who want to collect information from a JSON node based on the schema, the [walkers](doc/walkers.md) can help. The default JSON parser is the [Jackson](https://github.com/FasterXML/jackson) that is the most popular one. As it is a key component in our [light-4j](https://github.com/networknt/light-4j) microservices framework to validate request/response against OpenAPI specification for [light-rest-4j](http://www.networknt.com/style/light-rest-4j/) and RPC schema for [light-hybrid-4j](http://www.networknt.com/style/light-hybrid-4j/) at runtime, performance is the most important aspect in the design.
15
+
This is a Java implementation of the [JSON Schema Core Draft v4, v6, v7, v2019-09 and v2020-12](http://json-schema.org/latest/json-schema-core.html) specification for JSON schema validation.
16
+
17
+
In addition, it also works for OpenAPI 3.0 request/response validation with some [configuration flags](doc/config.md). For users who want to collect information from a JSON node based on the schema, the [walkers](doc/walkers.md) can help. The default JSON parser is the [Jackson](https://github.com/FasterXML/jackson) that is the most popular one. As it is a key component in our [light-4j](https://github.com/networknt/light-4j) microservices framework to validate request/response against OpenAPI specification for [light-rest-4j](http://www.networknt.com/style/light-rest-4j/) and RPC schema for [light-hybrid-4j](http://www.networknt.com/style/light-hybrid-4j/) at runtime, performance is the most important aspect in the design.
18
+
19
+
## JSON Schema Draft Specification Compatibility
20
+
21
+
Information on the compatibility support for each version, including known issues, can be found in the [Compatibility with JSON Schema versions](doc/compatibility.md) document.
22
+
23
+
## Upgrading to new versions
24
+
25
+
Information on notable or breaking changes when upgrading the library can be found in the [Upgrading to new versions](doc/upgrading.md) document. This library can contain breaking changes in minor version releases.
26
+
27
+
For the latest version, please check the [Releases](https://github.com/networknt/json-schema-validator/releases) page.
16
28
17
29
## Why this library
18
30
@@ -42,23 +54,67 @@ The OpenAPI 3.0 specification is using JSON schema to validate the request/respo
42
54
43
55
Following the design principle of the Light Platform, this library has minimum dependencies to ensure there are no dependency conflicts when using it.
44
56
45
-
Here are the dependencies:
57
+
The following are the dependencies that will automatically be included when this library is included.
<!-- Used to validate RFC 3339 date and date-time -->
83
+
<groupId>com.ethlo.time</groupId>
84
+
<artifactId>itu</artifactId>
85
+
<version>${version.itu}</version>
58
86
</dependency>
59
87
```
60
88
61
-
**Note**: Up to version [1.0.81](https://github.com/networknt/json-schema-validator/blob/1.0.81/pom.xml#L99), the dependency `org.apache.commons:commons-lang3` was included as a runtime dependency. Starting with [1.0.82](https://github.com/networknt/json-schema-validator/releases/tag/1.0.82) it is not required anymore.
89
+
The following are the optional dependencies that may be required for certain options.
90
+
91
+
These are not automatically included and setting the relevant option without adding the library will result in a `ClassNotFoundException`.
92
+
93
+
```xml
94
+
<!-- This is required when setting setEcma262Validator(true) -->
95
+
<dependency>
96
+
<!-- Used to validate ECMA 262 regular expressions -->
97
+
<groupId>org.jruby.joni</groupId>
98
+
<artifactId>joni</artifactId>
99
+
<version>${version.joni}</version>
100
+
<optional>true</optional>
101
+
</dependency>
102
+
```
103
+
104
+
The YAML dependency can be excluded if this is not required. Attempting to process schemas or input that are YAML will result in a `ClassNotFoundException`.
@@ -68,37 +124,110 @@ This library is very active with a lot of contributors. New features and bug fix
68
124
69
125
The library supports Java 8 and up. If you want to build from the source code, you need to install JDK 8 locally. To support multiple version of JDK, you can use [SDKMAN](https://www.networknt.com/tool/sdk/)
70
126
71
-
## Dependency
127
+
## Usage
128
+
129
+
### Adding the dependency
72
130
73
131
This package is available on Maven central.
74
132
75
-
Maven:
133
+
#### Maven:
76
134
77
135
```xml
78
136
<dependency>
79
137
<groupId>com.networknt</groupId>
80
138
<artifactId>json-schema-validator</artifactId>
81
-
<version>1.0.87</version>
82
-
83
-
<!-- Only required for versions < 1.0.82. See README.md -->
For the latest version, please check the [release](https://github.com/networknt/json-schema-validator/releases) page.
151
+
### Validating inputs against a schema
152
+
153
+
The following example demonstrates how inputs is validated against a schema. It comprises the following steps.
154
+
155
+
* Creating a schema factory with the default schema dialect and how the schemas can be retrieved.
156
+
* Configuring mapping the `$id` to a retrieval URI using `schemaMappers`.
157
+
* Configuring how the schemas are loaded using the retrieval URI using `schemaLoaders`.
158
+
For instance a `Map<String, String> schemas` containing a mapping of retrieval URI to schema data as a `String` can by configured using `builder.schemaLoaders(schemaLoaders -> schemaLoaders.schemas(schemas))`. This also accepts a `Function<String, String> schemaRetrievalFunction`.
159
+
* Creating a configuration for controlling validator behavior.
160
+
* Loading a schema from a schema location along with the validator configuration.
161
+
* Using the schema to validate the data along with setting any execution specific configuration like for instance the locale or whether format assertions are enabled.
162
+
163
+
```java
164
+
// This creates a schema factory that will use Draft 2012-12 as the default if $schema is not specified in the schema data. If $schema is specified in the schema data then that schema dialect will be used instead and this version is ignored.
// By default JSON Path is used for reporting the instance location and evaluation path
172
+
config.setPathType(PathType.JSON_POINTER);
173
+
// By default the JDK regular expression implementation which is not ECMA 262 compliant is used
174
+
// Note that setting this to true requires including the optional joni dependency
175
+
// config.setEcma262Validator(true);
176
+
177
+
// Due to the mapping the schema will be retrieved from the classpath at classpath:schema/example-main.json. If the schema data does not specify an $id the absolute IRI of the schema location will be used as the $id.
I have just updated the test suites from the [official website](https://github.com/json-schema-org/JSON-Schema-Test-Suite) as the old ones were copied from another Java validator. Now there are several issues that need to be addressed. All of them are edge cases, in my opinion, but need to be investigated. As my old test suites were inherited from another Java JSON Schema Validator, I guess other Java Validator would have the same issues as these issues are in the Java language itself.
The [light-rest-4j](https://github.com/networknt/light-rest-4j), [light-graphql-4j](https://github.com/networknt/light-graphql-4j) and [light-hybrid-4j](https://github.com/networknt/light-hybrid-4j) use this library to validate the request and response based on the specifications. If you are using other frameworks like Spring Boot, you can use the [OpenApiValidator](https://github.com/mservicetech/openapi-schema-validation), a generic OpenAPI 3.0 validator based on the OpenAPI 3.0 specification.
Copy file name to clipboardExpand all lines: doc/compatibility.md
+63-11Lines changed: 63 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,3 +1,13 @@
1
+
## Compatibility with JSON Schema versions
2
+
3
+
This implementation does not currently generate annotations.
4
+
5
+
The `pattern` validator by default uses the JDK regular expression implementation which is not ECMA-262 compliant and is thus not compliant with the JSON Schema specification. The library can however be configured to use a ECMA-262 compliant regular expression implementation.
6
+
7
+
### Known Issues
8
+
* The `anyOf` applicator currently returns immediately on matching a schema. This results in the `unevaluatedItems` and `unevaluatedProperties` keywords potentially returning an incorrect result as the rest of the schemas in the `anyOf` aren't processed.
9
+
* The `unevaluatedItems` keyword does not currently consider `contains`.
Since Draft 2019-09, the `contentEncoding` keyword does not generate assertions. As the implementation currently does not collect annotations this only generates assertions in Draft 7.
83
+
84
+
#### Content Media Type
85
+
86
+
Since Draft 2019-09, the `contentMediaType` keyword does not generate assertions. As the implementation currently does not collect annotations this only generates assertions in Draft 7.
87
+
88
+
#### Content Schema
89
+
90
+
The `contentSchema` keyword does not generate assertions. As the implementation currently does not collect annotations this doesn't do anything.
91
+
92
+
#### Pattern
93
+
94
+
By default the `pattern` keyword uses the JDK regular expression implementation validating regular expressions.
95
+
96
+
This is not ECMA-262 compliant and is thus not compliant with the JSON Schema specification. This is however the more likely desired behavior as other logic will most likely be using the default JDK regular expression implementation to perform downstream processing.
97
+
98
+
The library can be configured to use a ECMA-262 compliant regular expression validator which is implemented using [joni](https://github.com/jruby/joni). This can be configured by setting `setEcma262Validator` to `true`.
99
+
100
+
This also requires adding the `joni` dependency.
101
+
102
+
```xml
103
+
<dependency>
104
+
<!-- Used to validate ECMA 262 regular expressions -->
105
+
<groupId>org.jruby.joni</groupId>
106
+
<artifactId>joni</artifactId>
107
+
<version>${version.joni}</version>
108
+
</dependency>
109
+
```
110
+
111
+
### Format
112
+
113
+
Since Draft 2019-09 the `format` keyword only generates annotations by default and does not generate assertions.
114
+
115
+
This can be configured on a schema basis by using a meta schema with the appropriate vocabulary.
Copy file name to clipboardExpand all lines: doc/config.md
-8Lines changed: 0 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -45,14 +45,6 @@ The default value is true in the SchemaValidatorsConfig object.
45
45
46
46
For more details, please refer to this [issue](https://github.com/networknt/json-schema-validator/issues/183).
47
47
48
-
49
-
* uriMappings
50
-
51
-
Map of public, typically internet-accessible schema URLs to alternate locations; this allows for offline validation of schemas that refer to public URLs. This is merged with any mappings the sonSchemaFactory
52
-
may have been built.
53
-
54
-
The type for this variable is `Map<String, String>`.
55
-
56
48
* javaSemantics
57
49
58
50
When set to true, use Java-specific semantics rather than native JavaScript semantics.
0 commit comments