Skip to content

Commit c70b2b7

Browse files
stevehustevehu
committed
fixes #205 Update README.md to add more content
1 parent 50925d1 commit c70b2b7

File tree

2 files changed

+175
-118
lines changed

2 files changed

+175
-118
lines changed

‎README.md

Lines changed: 83 additions & 118 deletions
Original file line numberDiff line numberDiff line change
@@ -1,51 +1,71 @@
1-
This is an implementation of the [JSON Schema Core Draft v4](http://json-schema.org/latest/json-schema-core.html) specification for OpenAPI 3.0. It uses the [Jackson](https://github.com/FasterXML/jackson) for json parsing.
2-
31
[Stack Overflow](https://stackoverflow.com/questions/tagged/light-4j) |
42
[Google Group](https://groups.google.com/forum/#!forum/light-4j) |
53
[Gitter Chat](https://gitter.im/networknt/light-rest-4j) |
64
[Subreddit](https://www.reddit.com/r/lightapi/) |
7-
[Youtube Channel](https://www.youtube.com/channel/UCHCRMWJVXw8iB7zKxF55Byw) |
8-
[Documentation](https://doc.networknt.com/library/json-overlay/) |
5+
[Youtube](https://www.youtube.com/channel/UCHCRMWJVXw8iB7zKxF55Byw) |
6+
[Documentation](https://doc.networknt.com/library/json-schema-validator/) |
97
[Javadocs](https://www.javadoc.io/doc/com.networknt/json-schema-validator) |
108
[Contribution Guide](https://doc.networknt.com/contribute/) |
119

1210
[![Build Status](https://travis-ci.org/networknt/json-schema-validator.svg?branch=master)](https://travis-ci.org/networknt/json-schema-validator)
1311

14-
# json-schema-validator
12+
This is a Java implementation of the [JSON Schema Core Draft v4-v7](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). 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.
13+
14+
## Why this library
1515

16-
A Java json schema validator that supports json schema draft v4. It is a key component in our
17-
[light-4j](https://github.com/networknt/light-4j) microservices framework to validate request
18-
against OpenAPI specification for [light-rest-4j](http://www.networknt.com/style/light-rest-4j/)
19-
and RPC schema for [light-hybrid-4j](http://www.networknt.com/style/light-hybrid-4j/) at runtime.
16+
#### Performance
2017

18+
It is the fastest Java JSON Schema Validator as far as I know. Here is the testing result compare with the other two open-source implementations. It is about 32 times faster than the Fge and five times faster than the Everit.
2119

22-
* [Why to use this library?](#why-to-use-this-library)
23-
* [Maven installation](#maven-installation)
24-
* [Quickstart](#quickstart)
20+
fge: 7130ms
2521

22+
everit-org: 1168ms
2623

24+
networknt: 223ms
2725

28-
# Why to use this library?
26+
You can run the performance tests for three libraries from [https://github.com/networknt/json-schema-validator-perftest](https://github.com/networknt/json-schema-validator-perftest)
2927

30-
* It is the fastest Java Json Schema Validator as far as I know. Here is the testing result compare with other two open
31-
source implementations. It is about 32 times faster than fge and 5 times faster than everit.
28+
#### Parser
3229

30+
It uses Jackson that is the most popular JSON parser in Java. If you are using Jackson parser already in your project, it is natural to choose this library over others for schema validation.
3331

34-
fge: 7130ms
32+
#### Dependency
3533

36-
everit-org: 1168ms
34+
Following the design principle of the Light Platform, this library has minimum dependencies to ensure there are no dependency conflicts when using it.
3735

38-
networknt: 223ms
36+
Here are the dependencies.
3937

40-
You can run the performance tests for three libraries from [https://github.com/networknt/json-schema-validator-perftest](https://github.com/networknt/json-schema-validator-perftest)
38+
```
39+
<dependency>
40+
<groupId>com.fasterxml.jackson.core</groupId>
41+
<artifactId>jackson-databind</artifactId>
42+
<version>${version.jackson}</version>
43+
</dependency>
44+
<dependency>
45+
<groupId>org.slf4j</groupId>
46+
<artifactId>slf4j-api</artifactId>
47+
<version>${version.slf4j}</version>
48+
</dependency>
49+
<dependency>
50+
<groupId>org.apache.commons</groupId>
51+
<artifactId>commons-lang3</artifactId>
52+
<version>${version.common-lang3}</version>
53+
</dependency>
54+
```
55+
56+
#### Community
4157

42-
* It uses Jackson which is the most popular JSON parser in Java.
58+
This library is very active with a lot of contributors. New features and bug fixes are handled quickly by the team members. Because it is an essential dependency of the [light-4j](https://github.com/networknt/light-4j) framework in the same GitHub organization, it will be evolved and maintained along with the framework.
4359

60+
## Prerequisite
4461

62+
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/)
4563

46-
## Maven installation
64+
## Dependency
4765

48-
Add the following to your `pom.xml`:
66+
This package is available on Maven central.
67+
68+
Maven:
4969

5070
```xml
5171
<dependency>
@@ -55,113 +75,58 @@ Add the following to your `pom.xml`:
5575
</dependency>
5676
```
5777

58-
## Quickstart
59-
60-
To use the validator, you need to have both JsonSchema object and JsonNode object constructed and there are many ways to do that. Here is my
61-
base test class that shows you several way to construct these from String, Stream, Url and JsonNode. Pay attention on JsonSchemaFactory class
62-
as it is the way to construct JsonSchema object.
63-
64-
65-
```java
66-
/*
67-
* Copyright (c) 2016 Network New Technologies Inc.
68-
*
69-
* Licensed under the Apache License, Version 2.0 (the "License");
70-
* you may not use this file except in compliance with the License.
71-
* You may obtain a copy of the License at
72-
*
73-
* http://www.apache.org/licenses/LICENSE-2.0
74-
*
75-
* Unless required by applicable law or agreed to in writing, software
76-
* distributed under the License is distributed on an "AS IS" BASIS,
77-
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
78-
* See the License for the specific language governing permissions and
79-
* limitations under the License.
80-
*/
81-
82-
package com.networknt.schema;
83-
84-
import com.fasterxml.jackson.databind.JsonNode;
85-
import com.fasterxml.jackson.databind.ObjectMapper;
86-
87-
import java.io.InputStream;
88-
import java.net.URL;
89-
90-
/**
91-
* Created by steve on 22/10/16.
92-
*/
93-
public class BaseJsonSchemaValidatorTest {
94-
protected JsonNode getJsonNodeFromClasspath(String name) throws Exception {
95-
InputStream is1 = Thread.currentThread().getContextClassLoader()
96-
.getResourceAsStream(name);
97-
98-
ObjectMapper mapper = new ObjectMapper();
99-
JsonNode node = mapper.readTree(is1);
100-
return node;
101-
}
102-
103-
protected JsonNode getJsonNodeFromStringContent(String content) throws Exception {
104-
ObjectMapper mapper = new ObjectMapper();
105-
JsonNode node = mapper.readTree(content);
106-
return node;
107-
}
108-
109-
protected JsonNode getJsonNodeFromUrl(String url) throws Exception {
110-
ObjectMapper mapper = new ObjectMapper();
111-
JsonNode node = mapper.readTree(new URL(url));
112-
return node;
113-
}
114-
115-
protected JsonSchema getJsonSchemaFromClasspath(String name) throws Exception {
116-
JsonSchemaFactory factory = JsonSchemaFactory.getInstance();
117-
InputStream is = Thread.currentThread().getContextClassLoader()
118-
.getResourceAsStream(name);
119-
JsonSchema schema = factory.getSchema(is);
120-
return schema;
121-
}
122-
123-
124-
protected JsonSchema getJsonSchemaFromStringContent(String schemaContent) throws Exception {
125-
JsonSchemaFactory factory = JsonSchemaFactory.getInstance();
126-
JsonSchema schema = factory.getSchema(schemaContent);
127-
return schema;
128-
}
129-
130-
protected JsonSchema getJsonSchemaFromUrl(String url) throws Exception {
131-
JsonSchemaFactory factory = JsonSchemaFactory.getInstance();
132-
JsonSchema schema = factory.getSchema(new URL(url));
133-
return schema;
134-
}
135-
136-
protected JsonSchema getJsonSchemaFromJsonNode(JsonNode jsonNode) throws Exception {
137-
JsonSchemaFactory factory = JsonSchemaFactory.getInstance();
138-
JsonSchema schema = factory.getSchema(jsonNode);
139-
return schema;
140-
}
141-
}
78+
Gradle:
14279

14380
```
144-
And the following is one of the test cases in one of the test classes extends from above base class. As you can see, it constructs
145-
JsonSchema and JsonNode from String.
81+
dependencies {
82+
compile(group: "com.networknt", name: "json-schema-validator", version: "1.0.24");
83+
}
84+
```
14685

147-
```java
148-
JsonSchema schema = getJsonSchemaFromStringContent("{\"enum\":[1, 2, 3, 4],\"enumErrorCode\":\"Not in the list\"}");
149-
JsonNode node = getJsonNodeFromStringContent("7");
150-
Set<ValidationMessage> errors = schema.validate(node);
151-
assertThat(errors.size(), is(1));
86+
For the latest version, please check the [release](https://github.com/networknt/json-schema-validator/releases) page.
15287

153-
```
88+
## [Quick Start](doc/quickstart.md)
15489

15590
## [Configuration](doc/config.md)
15691

15792
## Known issues
15893

159-
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
160-
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.
94+
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.
16195

16296
[#7](https://github.com/networknt/json-schema-validator/issues/7)
16397

164-
[#6](https://github.com/networknt/json-schema-validator/issues/6)
165-
16698
[#5](https://github.com/networknt/json-schema-validator/issues/5)
16799

100+
## Contributors
101+
102+
Thanks to the following people who have contributed to this project. If you are using this library, please consider to be a sponsor for one of the contributors.
103+
104+
[@stevehu](https://github.com/sponsors/stevehu)
105+
[@jiachen1120](https://github.com/jiachen1120)
106+
[@BalloonWen](https://github.com/BalloonWen)
107+
[@eskabetxe](https://github.com/eskabetxe)
108+
[@ddobrin](https://github.com/ddobrin)
109+
[@ehrmann](https://github.com/ehrmann)
110+
[@rhwood](https://github.com/rhwood)
111+
[@nitin1891](https://github.com/nitin1891)
112+
[@jawaff](https://github.com/jawaff)
113+
[@kosty](https://github.com/kosty)
114+
[@chenyan71](https://github.com/chenyan71)
115+
[@chrisken](https://github.com/chrisken)
116+
[@NicholasAzar](https://github.com/NicholasAzar)
117+
[@basinilya](https://github.com/basinilya)
118+
119+
For all contributors, please visit https://github.com/networknt/json-schema-validator/graphs/contributors
120+
121+
If you are a contributor, please join the [GitHub Sponsors](https://github.com/sponsors) and swithch the link to your sponsors dashboard via a PR.
122+
123+
## Sponsors
124+
125+
126+
### Individual Sponsors
127+
128+
129+
### Corporation Sponsors
130+
131+
132+

‎doc/quickstart.md

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
## Quick Start
2+
3+
To use the validator, you need to have both the JsonSchema object and JsonNode object constructed, and there are many ways to do that. Here is my base test class that shows you several ways to construct these from String, Stream, Url, and JsonNode. Pay attention to the JsonSchemaFactory class as it is the way to construct the JsonSchema object.
4+
5+
```java
6+
/*
7+
* Copyright (c) 2016 Network New Technologies Inc.
8+
*
9+
* Licensed under the Apache License, Version 2.0 (the "License");
10+
* you may not use this file except in compliance with the License.
11+
* You may obtain a copy of the License at
12+
*
13+
* http://www.apache.org/licenses/LICENSE-2.0
14+
*
15+
* Unless required by applicable law or agreed to in writing, software
16+
* distributed under the License is distributed on an "AS IS" BASIS,
17+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18+
* See the License for the specific language governing permissions and
19+
* limitations under the License.
20+
*/
21+
22+
package com.networknt.schema;
23+
24+
import com.fasterxml.jackson.databind.JsonNode;
25+
import com.fasterxml.jackson.databind.ObjectMapper;
26+
27+
import java.io.InputStream;
28+
import java.net.URL;
29+
30+
/**
31+
* Created by steve on 22/10/16.
32+
*/
33+
public class BaseJsonSchemaValidatorTest {
34+
protected JsonNode getJsonNodeFromClasspath(String name) throws Exception {
35+
InputStream is1 = Thread.currentThread().getContextClassLoader()
36+
.getResourceAsStream(name);
37+
38+
ObjectMapper mapper = new ObjectMapper();
39+
JsonNode node = mapper.readTree(is1);
40+
return node;
41+
}
42+
43+
protected JsonNode getJsonNodeFromStringContent(String content) throws Exception {
44+
ObjectMapper mapper = new ObjectMapper();
45+
JsonNode node = mapper.readTree(content);
46+
return node;
47+
}
48+
49+
protected JsonNode getJsonNodeFromUrl(String url) throws Exception {
50+
ObjectMapper mapper = new ObjectMapper();
51+
JsonNode node = mapper.readTree(new URL(url));
52+
return node;
53+
}
54+
55+
protected JsonSchema getJsonSchemaFromClasspath(String name) throws Exception {
56+
JsonSchemaFactory factory = JsonSchemaFactory.getInstance();
57+
InputStream is = Thread.currentThread().getContextClassLoader()
58+
.getResourceAsStream(name);
59+
JsonSchema schema = factory.getSchema(is);
60+
return schema;
61+
}
62+
63+
64+
protected JsonSchema getJsonSchemaFromStringContent(String schemaContent) throws Exception {
65+
JsonSchemaFactory factory = JsonSchemaFactory.getInstance();
66+
JsonSchema schema = factory.getSchema(schemaContent);
67+
return schema;
68+
}
69+
70+
protected JsonSchema getJsonSchemaFromUrl(String url) throws Exception {
71+
JsonSchemaFactory factory = JsonSchemaFactory.getInstance();
72+
JsonSchema schema = factory.getSchema(new URL(url));
73+
return schema;
74+
}
75+
76+
protected JsonSchema getJsonSchemaFromJsonNode(JsonNode jsonNode) throws Exception {
77+
JsonSchemaFactory factory = JsonSchemaFactory.getInstance();
78+
JsonSchema schema = factory.getSchema(jsonNode);
79+
return schema;
80+
}
81+
}
82+
83+
```
84+
And the following is one of the test cases in one of the test classes that extend from the above base class. As you can see, it constructs JsonSchema and JsonNode from String.
85+
86+
```java
87+
JsonSchema schema = getJsonSchemaFromStringContent("{\"enum\":[1, 2, 3, 4],\"enumErrorCode\":\"Not in the list\"}");
88+
JsonNode node = getJsonNodeFromStringContent("7");
89+
Set<ValidationMessage> errors = schema.validate(node);
90+
assertThat(errors.size(), is(1));
91+
92+
```

0 commit comments

Comments
 (0)