From dd340efeb45b990c954de6431246be90fd2ba924 Mon Sep 17 00:00:00 2001 From: leadpony Date: Mon, 27 Apr 2020 00:04:19 +0900 Subject: [PATCH] Bump version to 3.0.0-RC1 --- CHANGELOG.md | 6 +- README-v2.md | 281 ++++++++++++++++++++++++++++++++++++++++++ README.md | 53 +++----- justify-cli/pom.xml | 2 +- justify-tests/pom.xml | 2 +- justify/pom.xml | 2 +- pom.xml | 4 +- 7 files changed, 306 insertions(+), 44 deletions(-) create mode 100644 README-v2.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 7fabff16..8185ccba 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,12 +4,12 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## Unreleased +## 3.0.0-RC1 - 2020-04-27 ### Changed -- Updated Jakarta JSON Processing API to 2.0.0, which causes the API package `javax.json` to be migirated to `jakarta.json`. +- Updated Jakarta JSON Processing API to 2.0.0, which causes the API package `javax.json` to be migrated to `jakarta.json`. ### Fixed -- Fixed a bug which was causing auto detection of schema version to fail. +- Fixed a bug which was causing automatic detection of schema version to fail. ## 2.1.0 - 2020-04-02 ### Added diff --git a/README-v2.md b/README-v2.md new file mode 100644 index 00000000..08f1a8ad --- /dev/null +++ b/README-v2.md @@ -0,0 +1,281 @@ +# Justify +[![Apache 2.0 License](https://img.shields.io/:license-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0) +[![Maven Central](https://img.shields.io/maven-central/v/org.leadpony.justify/justify.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22org.leadpony.justify%22%20AND%20a:%22justify%22) +[![Javadocs](https://www.javadoc.io/badge/org.leadpony.justify/justify.svg?color=green)](https://www.javadoc.io/doc/org.leadpony.justify/justify) +[![Build Status](https://travis-ci.org/leadpony/justify.svg?branch=master)](https://travis-ci.org/leadpony/justify) + +Justify is a JSON validator based on [JSON Schema Specification] and [Java API for JSON Processing (JSR 374)]. + +## Key Features + +* Compliant with [JSON Schema Specification] Draft-07, -06, and -04. +* Reinforces [Java API for JSON Processing (JSR 374)] transparently with the validation functionality. +* Can be used with [Java API for JSON Binding (JSR 367)] via a custom JsonProvider. +* Reports problems with the source locations including line and column numbers. +* Passes all test cases provided by [JSON Schema Test Suite] including both mandatory and optional tests. +* Validates the input in streaming way, which claims small memory footprint even when the input is a large JSON. +* Accepts custom formats for string and other simple types. +* Supports Java 8, 9, 10, 11, and 12. +* Can be used as a modular jar in Java 9 and higher. +* Internationalized problem messages, including Japanese language support. + +## Getting Started + +### Minimum Setup + +This software is available in the [Maven Central Repository] and the following dependency should be added to your build. + +*Maven* +```xml + + org.leadpony.justify + justify + 2.1.0 + +``` + +*Gradle* +``` +implementation group: 'org.leadpony.justify', name: 'justify', version: '2.1.0' +``` + +Note that the addition of this dependency brings the following artifacts as transitive dependencies. + +* `jakarta.json:jakarta.json-api` +* `com.ibm.icu:icu4j` + +Besides the library itself, one of [Java API for JSON Processing (JSR 374)] implementations is needed during runtime. +This library supports the following implementations and you can select whichever you prefer. +1. [Jakarta JSON Processing] +2. [Apache Johnzon] +3. [Joy] + +Please add exactly one dependency to your build as shown below. + +#### Jakarta JSON Processing +*Maven* +```xml + + org.glassfish + jakarta.json + module + 1.1.6 + runtime + +``` + +*Gradle* +``` +runtimeOnly group: 'org.glassfish', name: 'jakarta.json', classifier: 'module', version: '1.1.6' +``` + +Please note that the classifier `module` is required when using this implementation. + +#### Apache Johnzon +*Maven* +```xml + + org.apache.johnzon + johnzon-core + 1.2.1 + runtime + +``` + +*Gradle* +``` +runtimeOnly group: 'org.apache.johnzon', name: 'johnzon-core', version: '1.2.1' +``` + +#### Joy +*Maven* +```xml + + org.leadpony.joy + joy + 1.2.0 + runtime + +``` + +*Gradle* +``` +runtimeOnly group: 'org.leadpony.joy', name: 'joy', version: '1.2.0' +``` + +### Using with the Streaming API of JSON Processing + +```java +JsonValidationService service = JsonValidationService.newInstance(); + +// Reads the JSON schema +JsonSchema schema = service.readSchema(Paths.get("news.schema.json")); + +// Problem handler which will print problems found. +ProblemHandler handler = service.createProblemPrinter(System.out::println); + +Path path = Paths.get("fake-news.json"); +// Parses the JSON instance by javax.json.stream.JsonParser +try (JsonParser parser = service.createParser(path, schema, handler)) { + while (parser.hasNext()) { + JsonParser.Event event = parser.next(); + // Do something useful here + } +} +``` + +### Using with the Object Model API of JSON Processing + +```java +JsonValidationService service = JsonValidationService.newInstance(); + +// Reads the JSON schema +JsonSchema schema = service.readSchema(Paths.get("news.schema.json")); + +// Problem handler which will print problems found. +ProblemHandler handler = service.createProblemPrinter(System.out::println); + +Path path = Paths.get("fake-news.json"); +// Reads the JSON instance by javax.json.JsonReader +try (JsonReader reader = service.createReader(path, schema, handler)) { + JsonValue value = reader.readValue(); + // Do something useful here +} +``` + +## Command-Line Interface + +Justify CLI is a command-line wrapper of Justify library. +This utility can be used to validate JSON documents against JSON schemas without writing any code. + +### Downloads + +Check the [Releases] page to get the latest distribution in `tar.gz` or `zip` format, +whichever you prefer. The software requires Java 8 or higher to run. + +### Usage + +After unpacking the downloaded file, just typing the following command validates a JSON instance against a JSON schema. + +```bash +$ ./justify -s -i +``` + +The following command validates a JSON schema against its metaschema. + +```bash +$ ./justify -s +``` + +#### Options + +##### -s __ + +Required option to specify a path to a JSON schema against which one or more JSON instances will be validated. + +##### -i __ ... + +Optional option to specify a path to a JSON instance to be validated. +Multiple instances can be specified using whitespace as a delimiter. + +##### -r __ ... + +Optional option to specify a path to a JSON schema to be referenced by other JSON schemas. +Multiple schemas can be specified using whitespace as a delimiter. + +##### -h + +Displays all available options including those shown above. + +## Additional Resources + +* [Justify Examples] which show how to use this library. +* [API Reference in Javadoc] +* [Changelog] + +## Conformance to Specification + +This software is one of the most correct implementation of the JSON Schema Specification. Please refer to the result of [JSON Schema Conformance Test]. + +## Completion by `default` Keyword + +The missing properties and/or items in the instance can be filled with default values provided by `default` keyword while it is being validated. + +For example, the input JSON instance shown below +```json +{ + "red": 64, + "green": 128, + "blue": 192 +} +``` + +will be filled with the default value and modified to: +```json +{ + "red": 64, + "green": 128, + "blue": 192, + "alpha": 255 +} +``` + +Both `JsonParser` and `JsonReader` support the feature. `JsonParser` produces additional events caused by the default values and `JsonReader` expands objects and arrays with the additional values. + +By default, this feature is disabled and the instance never be modified. The following code shows how to explicitly enable the feature for the parsers and readers. + +```java +ValidationConfig config = service.createValidationConfig(); +config.withSchema(schema) + .withProblemHandler(handler) + .withDefaultValues(true); // This enables the feature. +// For retrieving parser factory +JsonParserFactory parserFactory = service.createParserFactory(config.getAsMap()); +// Or for retrieving reader factory +JsonReaderFactory readerFactory = service.createReaderFactory(config.getAsMap()); +``` + +For more information, please see [the code sample](https://github.com/leadpony/justify-examples/tree/master/justify-examples-defaultvalue). + +## Building from Source + +The following tools are required to build this software. +* [JDK] 11 +* [Apache Maven] 3.6.2 or higher + +The commands below build this software and install it into your local Maven repository. + +```bash +$ git clone --recursive https://github.com/leadpony/justify.git +$ cd justify +$ mvn clean install -P release +``` + +## Similar Solutions + +There exist several JSON validator implementations conformant to the JSON Schema Specification, including those for other programming languages. [The list of implementations] is available on the JSON Schema web site. + +## Copyright Notice +Copyright © 2018-2020 the Justify authors. This software is licensed under [Apache License, Versions 2.0][Apache 2.0 License]. + +[Apache 2.0 License]: https://www.apache.org/licenses/LICENSE-2.0 +[Apache Johnzon]: https://johnzon.apache.org/ +[Apache Maven]: https://maven.apache.org/ +[API Reference in Javadoc]: https://www.javadoc.io/doc/org.leadpony.justify/justify +[Changelog]: CHANGELOG.md +[everit-org/json-schema]: https://github.com/everit-org/json-schema +[Jakarta JSON Processing]: https://github.com/eclipse-ee4j/jsonp +[Java API for JSON Processing (JSR 374)]: https://eclipse-ee4j.github.io/jsonp/ +[Java API for JSON Binding (JSR 367)]: http://json-b.net/ +[java-json-tools/json-schema-validator]: https://github.com/java-json-tools/json-schema-validator +[JDK]: https://jdk.java.net/ +[Joy]: https://github.com/leadpony/joy +[JSON Schema Conformance Test]: https://github.com/leadpony/json-schema-conformance-test +[JSON Schema Specification]: https://json-schema.org/ +[JSON Schema Test Suite]: https://github.com/json-schema-org/JSON-Schema-Test-Suite +[Justify CLI]: https://github.com/leadpony/justify-cli +[Justify Examples]: https://github.com/leadpony/justify-examples +[Maven Central Repository]: https://mvnrepository.com/repos/central +[networknt/json-schema-validator]: https://github.com/networknt/json-schema-validator +[Releases]: https://github.com/leadpony/justify/releases/latest +[The list of implementations]: https://json-schema.org/implementations.html diff --git a/README.md b/README.md index 08f1a8ad..d32aae1d 100644 --- a/README.md +++ b/README.md @@ -4,13 +4,13 @@ [![Javadocs](https://www.javadoc.io/badge/org.leadpony.justify/justify.svg?color=green)](https://www.javadoc.io/doc/org.leadpony.justify/justify) [![Build Status](https://travis-ci.org/leadpony/justify.svg?branch=master)](https://travis-ci.org/leadpony/justify) -Justify is a JSON validator based on [JSON Schema Specification] and [Java API for JSON Processing (JSR 374)]. +Justify is a JSON validator based on [JSON Schema Specification] and [Jakarta JSON Processing] (JSON-P). ## Key Features * Compliant with [JSON Schema Specification] Draft-07, -06, and -04. -* Reinforces [Java API for JSON Processing (JSR 374)] transparently with the validation functionality. -* Can be used with [Java API for JSON Binding (JSR 367)] via a custom JsonProvider. +* Reinforces [Jakarta JSON Processing] (JSON-P) transparently with the validation functionality. +* Can be used with [Jakarta JSON Binding] (JSON-B) via a custom JsonProvider. * Reports problems with the source locations including line and column numbers. * Passes all test cases provided by [JSON Schema Test Suite] including both mandatory and optional tests. * Validates the input in streaming way, which claims small memory footprint even when the input is a large JSON. @@ -21,6 +21,9 @@ Justify is a JSON validator based on [JSON Schema Specification] and [Java API f ## Getting Started +_For Justify version 2.x users:_ +Please refer to old [README](./README-v2.md) for the instructions. + ### Minimum Setup This software is available in the [Maven Central Repository] and the following dependency should be added to your build. @@ -30,13 +33,13 @@ This software is available in the [Maven Central Repository] and the following d org.leadpony.justify justify - 2.1.0 + 3.0.0-RC1 ``` *Gradle* ``` -implementation group: 'org.leadpony.justify', name: 'justify', version: '2.1.0' +implementation group: 'org.leadpony.justify', name: 'justify', version: '3.0.0-RC1' ``` Note that the addition of this dependency brings the following artifacts as transitive dependencies. @@ -44,11 +47,10 @@ Note that the addition of this dependency brings the following artifacts as tran * `jakarta.json:jakarta.json-api` * `com.ibm.icu:icu4j` -Besides the library itself, one of [Java API for JSON Processing (JSR 374)] implementations is needed during runtime. +Besides the library itself, one of [Jakarta JSON Processing] implementations is needed during runtime. This library supports the following implementations and you can select whichever you prefer. 1. [Jakarta JSON Processing] -2. [Apache Johnzon] -3. [Joy] +2. [Joy] Please add exactly one dependency to your build as shown below. @@ -59,48 +61,32 @@ Please add exactly one dependency to your build as shown below. org.glassfish jakarta.json module - 1.1.6 + 2.0.0-RC2 runtime ``` *Gradle* ``` -runtimeOnly group: 'org.glassfish', name: 'jakarta.json', classifier: 'module', version: '1.1.6' +runtimeOnly group: 'org.glassfish', name: 'jakarta.json', classifier: 'module', version: '2.0.0-RC2' ``` Please note that the classifier `module` is required when using this implementation. -#### Apache Johnzon -*Maven* -```xml - - org.apache.johnzon - johnzon-core - 1.2.1 - runtime - -``` - -*Gradle* -``` -runtimeOnly group: 'org.apache.johnzon', name: 'johnzon-core', version: '1.2.1' -``` - #### Joy *Maven* ```xml org.leadpony.joy - joy - 1.2.0 + joy-classic + 2.0.0-RC2 runtime ``` *Gradle* ``` -runtimeOnly group: 'org.leadpony.joy', name: 'joy', version: '1.2.0' +runtimeOnly group: 'org.leadpony.joy', name: 'joy', version: '2.0.0-RC2' ``` ### Using with the Streaming API of JSON Processing @@ -259,15 +245,11 @@ There exist several JSON validator implementations conformant to the JSON Schema Copyright © 2018-2020 the Justify authors. This software is licensed under [Apache License, Versions 2.0][Apache 2.0 License]. [Apache 2.0 License]: https://www.apache.org/licenses/LICENSE-2.0 -[Apache Johnzon]: https://johnzon.apache.org/ [Apache Maven]: https://maven.apache.org/ [API Reference in Javadoc]: https://www.javadoc.io/doc/org.leadpony.justify/justify [Changelog]: CHANGELOG.md -[everit-org/json-schema]: https://github.com/everit-org/json-schema -[Jakarta JSON Processing]: https://github.com/eclipse-ee4j/jsonp -[Java API for JSON Processing (JSR 374)]: https://eclipse-ee4j.github.io/jsonp/ -[Java API for JSON Binding (JSR 367)]: http://json-b.net/ -[java-json-tools/json-schema-validator]: https://github.com/java-json-tools/json-schema-validator +[Jakarta JSON Processing]: https://eclipse-ee4j.github.io/jsonp/ +[Jakarta JSON Binding]: http://json-b.net/ [JDK]: https://jdk.java.net/ [Joy]: https://github.com/leadpony/joy [JSON Schema Conformance Test]: https://github.com/leadpony/json-schema-conformance-test @@ -276,6 +258,5 @@ Copyright © 2018-2020 the Justify authors. This software is licensed under [Justify CLI]: https://github.com/leadpony/justify-cli [Justify Examples]: https://github.com/leadpony/justify-examples [Maven Central Repository]: https://mvnrepository.com/repos/central -[networknt/json-schema-validator]: https://github.com/networknt/json-schema-validator [Releases]: https://github.com/leadpony/justify/releases/latest [The list of implementations]: https://json-schema.org/implementations.html diff --git a/justify-cli/pom.xml b/justify-cli/pom.xml index 9ab3804c..e9122332 100644 --- a/justify-cli/pom.xml +++ b/justify-cli/pom.xml @@ -8,7 +8,7 @@ org.leadpony.justify justify-parent - 3.0.0-SNAPSHOT + 3.0.0-RC1 justify-cli diff --git a/justify-tests/pom.xml b/justify-tests/pom.xml index 66118630..86133696 100644 --- a/justify-tests/pom.xml +++ b/justify-tests/pom.xml @@ -8,7 +8,7 @@ org.leadpony.justify justify-parent - 3.0.0-SNAPSHOT + 3.0.0-RC1 justify-tests diff --git a/justify/pom.xml b/justify/pom.xml index 65059bc5..ce782d48 100644 --- a/justify/pom.xml +++ b/justify/pom.xml @@ -8,7 +8,7 @@ org.leadpony.justify justify-parent - 3.0.0-SNAPSHOT + 3.0.0-RC1 justify diff --git a/pom.xml b/pom.xml index 89463b67..c565e360 100644 --- a/pom.xml +++ b/pom.xml @@ -7,7 +7,7 @@ org.leadpony.justify justify-parent - 3.0.0-SNAPSHOT + 3.0.0-RC1 pom org.leadpony.justify.parent @@ -39,7 +39,7 @@ com.ibm.icu icu4j - 65.1 + 67.1 org.junit.jupiter