json-schema-validator

Stack Overflow | Google Group | Gitter Chat | Subreddit | Youtube | Documentation | Contribution Guide | This is a Java implementation of the JSON Schema Core Draft v4, v6, v7, v2019-09 and v2020-12 specification for JSON schema validation. This implementation supports Customizing Dialects, Vocabularies, Keywords and Formats.

The JSON parser used is the Jackson parser.

OpenAPI 3 request/response validation is supported with the use of the appropriate dialect.

As it is a key component in our light-4j microservices framework to validate request/response against OpenAPI specification for light-rest-4j and RPC schema for light-hybrid-4j at runtime, performance is the most important aspect in the design.

JSON Schema Specification compatibility

Information on the compatibility support for each version, including known issues, can be found in the Compatibility with JSON Schema versions document.

Since Draft 2019-09 the format keyword only generates annotations by default and does not generate assertions.

This behavior can be overridden to generate assertions by setting the formatAssertionsEnabled to true in SchemaRegistryConfig or ExecutionConfig.

Upgrading to new versions

This library can contain breaking changes in minor version releases that may require code changes.

Information on notable or breaking changes when upgrading the library can be found in the Upgrading to new versions document.

The Releases page will contain information on the latest versions.

Comparing against other implementations

The JSON Schema Validation Comparison project from Creek has an informative Comparison of JVM based Schema Validation Implementations which compares both the functional and performance characteristics of a number of different Java implementations.

• Functional comparison
• Performance comparison

The Bowtie project has a report that compares functional characteristics of different implementations, including non-Java implementations, but does not do any performance benchmarking.

Why this library

Performance

The following is the benchmark results from the JSON Schema Validator Perftest project that uses the Java Microbenchmark Harness.

Note that the benchmark results are highly dependent on the input data workloads and schemas used for the validation.

In this case this workload is using the Draft 4 specification and largely tests the performance of the evaluating the properties keyword. You may refer to Results of performance comparison of JVM based JSON Schema Validation Implementations for benchmark results that use the JSON Schema Test Suite.

If performance is an important consideration, the specific sample workloads should be benchmarked, as there are different performance characteristics when certain keywords are used. For instance the use of the unevaluatedProperties or unevaluatedItems keyword will trigger annotation collection in the related validators, such as the properties or items validators, and annotation collection will adversely affect performance.

Special attention should also be made for inefficient schemas using deeply nested oneOf or anyOf that do not have a condition to short-circuit the evaluation using if and then. The validator has no choice but to perform all the evaluations, and the error messages would be typically very confusing as it will return all the messages from the children.

NetworkNT 2.0.0

Benchmark                                     Mode  Cnt       Score     Error   Units
NetworkntBenchmark.basic                     thrpt   10    5297.105 ± 290.078   ops/s
NetworkntBenchmark.basic:gc.alloc.rate       thrpt   10    1618.328 ±  88.626  MB/sec
NetworkntBenchmark.basic:gc.alloc.rate.norm  thrpt   10  320360.020 ±   0.002    B/op
NetworkntBenchmark.basic:gc.count            thrpt   10     365.000            counts
NetworkntBenchmark.basic:gc.time             thrpt   10     130.000                ms

Everit 1.14.6

Benchmark                                     Mode  Cnt       Score     Error   Units
EveritBenchmark.basic                        thrpt   10    4615.637 ± 151.195   ops/s
EveritBenchmark.basic:gc.alloc.rate          thrpt   10    2097.810 ±  68.708  MB/sec
EveritBenchmark.basic:gc.alloc.rate.norm     thrpt   10  476592.023 ±   0.001    B/op
EveritBenchmark.basic:gc.count               thrpt   10     521.000            counts
EveritBenchmark.basic:gc.time                thrpt   10     170.000                ms

Functionality

This implementation is tested against the JSON Schema Test Suite. As tests are continually added to the suite, these test results may not be current.

• Note that this uses the JoniRegularExpressionFactory for the pattern and format regex tests.

Jackson Parser

This library uses Jackson which is a Java JSON parser that is widely used in other projects. If you are already using the Jackson parser in your project, it is natural to choose this library over others for schema validation.

YAML Support

The library works with JSON and YAML on both schema definitions and input data.

OpenAPI Support

The OpenAPI 3.0 specification is using JSON schema to validate the request/response. The library has support for the OpenAPI 3.0 and OpenAPI 3.1 dialects.

Minimal Dependencies

Following the design principle of the Light Platform, this library has minimal dependencies to ensure there are no dependency conflicts when using it.

Required Dependencies

The following are the dependencies that will automatically be included when this library is included.

    
    org.slf4j
    slf4j-api
    ${version.slf4j}

    
    com.fasterxml.jackson.core
    jackson-databind
    ${version.jackson}

    
    com.fasterxml.jackson.dataformat
    jackson-dataformat-yaml
    ${version.jackson}

    
    com.ethlo.time
    itu
    ${version.itu}

Optional Dependencies

The following are the optional dependencies that may be required for certain options.

These are not automatically included and setting the relevant option without adding the library will result in a ClassNotFoundException.

    
    
    
    org.graalvm.js
    js
    ${version.graaljs}

    
    
    
    org.jruby.joni
    joni
    ${version.joni}

Excludable Dependencies

The following are required dependencies that are automatically included, but can be explicitly excluded if they are not required.

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.

    com.networknt
    json-schema-validator
    
        
            com.fasterxml.jackson.dataformat
            jackson-dataformat-yaml
        
    

The Ethlo Time dependency can be excluded if accurate validation of the date-time format is not required. The date-time format will then use java.time.OffsetDateTime to determine if the date-time is valid .

    com.networknt
    json-schema-validator
    
        
            com.ethlo.time
            itu
        
    

Community

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 framework in the same GitHub organization, it will be evolved and maintained along with the framework.

Prerequisite

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

Usage

Adding the dependency

The json-schema-validator package is published to Maven Central and is available in two major release lines, depending on your Java and Jackson versions:

• 2.x.x — Compatible with Java 8+ and Jackson 2.x
• 3.x.x — Compatible with Java 17+ and Jackson 3.x

Maven:

Jackson 2 (Java 8+)

    com.networknt
    json-schema-validator
    2.0.4

Jackson 3 (Java 17+)

    com.networknt
    json-schema-validator
    3.0.7

Gradle:

Jackson 2 (Java 8+)

dependencies {
    implementation(group: 'com.networknt', name: 'json-schema-validator', version: '2.0.4');
}

Jackson 3 (Java 17+)

dependencies {
    implementation(group: 'com.networknt', name: 'json-schema-validator', version: '3.0.7');
}

Validating inputs against a schema

The following example demonstrates how inputs are validated against a schema. It comprises the following steps.

• Creating a configuration for controlling validator behavior.
• Creating a schema registry with the default schema dialect and how the schemas can be retrieved.
  • Configuring mapping the $id to a retrieval IRI using schemaIdResolvers.
  • Configuring how the schemas are loaded using the retrieval IRI. For instance a Map schemas containing a mapping o