json-schema-validator: a fast Java validator for five JSON Schema drafts

Five drafts, and a design driven by runtime validation cost

json-schema-validator is a Java implementation of the JSON Schema Core specification, and it covers draft v4, v6, v7, v2019-09 and v2020-12. The JSON parser it uses is Jackson.

The reason the project exists in this form is stated in the README. It is a key component in the light-4j microservices framework, used to validate requests and responses against an OpenAPI specification for light-rest-4j and against an RPC schema for light-hybrid-4j at runtime. Because of that, performance is the most important aspect in the design.

That framing explains the rest of the library. This is not a general-purpose validator that happens to be fast, it is a validator built for the case where a service validates a payload on every inbound request, and the cost of that validation is part of the request budget.

The draft coverage is checked against an external compliance suite. The README links Bowtie badges for supported dialects and for compliance on each of draft 2020-12, 2019-09, 7, 6 and 4, and points at the Compatibility with JSON Schema versions document for the per-version support detail including known issues.

Beyond plain JSON Schema, OpenAPI 3 request and response validation is supported with the use of the appropriate dialect, and the implementation supports customizing dialects, vocabularies, keywords and formats. That extension surface is the other reason to pick this library over a simpler one: in a microservice framework, different services often need different rules, and a hard-coded keyword set would be a problem.

format generates annotations, not assertions, unless you change it

There is one behaviour in this library that catches people out, and the README puts it near the top of the document.

Since draft 2019-09, the `format` keyword only generates annotations by default and does not generate assertions. In other words, a string that claims to be a date but is not one will be reported as annotated, not rejected, unless you ask otherwise.

That behaviour is specified rather than accidental, so the library is right to follow it. But most people arrive at JSON Schema validation from a system where `format` did fail the value, and the change in semantics between drafts is exactly the kind of thing that produces a production incident where invalid dates start passing.

The override is a configuration flag. This behaviour can be overridden to generate assertions by setting the `formatAssertionsEnabled` to `true` in `SchemaRegistryConfig` or `ExecutionConfig`.

Two things make this worth checking carefully in your own schemas. First, the setting is per registry or per execution, so it can differ between two validation paths in the same application without that being obvious. Second, the annotation behaviour is still recorded, so a value that fails `format` is not silently ignored, it is annotated, which is useful if you want to report on it rather than reject on it.

The dialect and vocabulary system is where this kind of policy lives. Since a dialect can redefine what a keyword means, a project that needs `format` to assert can express that as a dialect rather than as a scattered configuration change, and the same mechanism is available for custom keywords that the standard does not cover.

The performance story comes with its own caveats

The README's performance section is careful, and the caveats are as informative as the numbers.

The benchmark results come from a separate project, the JSON Schema Validator Perftest, which uses the Java Microbenchmark Harness. The note that follows is the important one: the benchmark results are highly dependent on the input data workloads and schemas used for the validation. The particular workload described uses the draft 4 specification and largely tests the performance of evaluating the `properties` keyword.

The advice the project gives is to benchmark your own sample workloads if performance matters, because different keywords have different performance characteristics. Two concrete examples are given.

The first is annotation collection. 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. That is a direct consequence of the draft 2019-09 model, where a keyword cannot know what a sibling keyword did without collecting what it did.

The second is schema structure rather than keyword choice. Special attention should 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.

That last point is a usability problem as much as a performance one. A schema with five nested `anyOf` branches produces an error report listing every branch's failures, and the caller has to work out which branch was intended. If you are writing schemas by hand for an OpenAPI contract, that structure is a design smell worth fixing at the source.

How this compares with other JVM validators

The README does not claim a monopoly, and it points at two comparison efforts rather than at its own table alone.

The first is the JSON Schema Validation Comparison project from Creek, which has a Comparison of JVM based Schema Validation Implementations covering both the functional and the performance characteristics of a number of different Java implementations. The README links the functional comparison and the performance comparison separately, and the performance one uses the JSON Schema Test Suite as its workload.

The second is Bowtie, the cross-implementation project, which compares the functional characteristics of different implementations including non-Java ones, but does not do any performance benchmarking.

The split between those two is itself informative. Bowtie answers the question of which implementations agree with the specification. The Creek project answers the question of which implementation is faster on a JVM, which is a question that only matters if you are validating on the hot path of a Java service.

So the honest way to read this project is that it competes on two axes at once, specification fidelity across five drafts, checked publicly, and JVM throughput, checked by a third party. The Bowtie compliance badges in the README are the evidence for the first axis, and the third-party comparison is the evidence for the second.

The alternative worth naming is not another Java library but a different approach: validating at the edge, in a gateway or an API platform that terminates requests, and letting the service behind it trust its input. That removes the per-request cost from the service entirely, and it moves the schema out of the code. The trade is that the validation now happens somewhere your application team does not control, and the schema is no longer versioned alongside the service.

Two release lines, and breaking changes in minor versions

The version picture needs a second look, because there are two lines moving at once.

The listed releases are 3.0.7 on 2026-08-20, 3.0.8 on 2026-09-30 and 2.0.8 on 2026-10-02. So the 2.x line received a release two days after the 3.0.8 tag, which means both lines are being maintained rather than the 2.x line being abandoned.

The repository topic list includes `java8`, which is consistent with a maintained older line, and the description mentions the project supports draft v4 through v2020-12. The README itself does not state which line targets which Java version, so the mapping between the two lines and the Java versions is something to confirm in the release notes rather than assume.

The upgrade guidance is blunt and is worth reading before you touch either line. This library can contain breaking changes in `minor` version releases that may require code changes. That is unusual for a mature library and it is stated plainly, with a pointer to the Upgrading to new versions document for information on notable or breaking changes, and the Releases page carrying the latest information.

The reason to believe that is that the project has a documented upgrade path rather than just a warning, and a `CHANGELOG.md` at the repository root, but the practical consequence is that a routine dependency bump on this library is not the routine dependency bump you have on everything else. Pin it deliberately and read the changelog.

For the rest of the project, the layout is conventional for a Maven library: a `pom.xml` at the root, `src/` for the code and tests, a `doc/` directory holding the Markdown documents the README links to, and a `LICENSE` and `NOTICE` pair. The `doc/` directory is where the compatibility notes, the custom dialect guide, the OpenAPI guide and the upgrade guide live, so the substantive documentation is in the repository rather than only on a website.

Editorial conclusion

json-schema-validator fits a Java team validating request and response payloads against OpenAPI or JSON Schema at runtime, in a microservice where validation happens on every call and throughput matters. It does not fit a service that wants a non-Java runtime, and it does not fit a project that assumes `format` will reject a malformed date or email. Verify first which draft your schemas use and whether the version you pick implements it as you expect, since the library tracks five drafts and the compatibility document records known issues per version, that `formatAssertionsEnabled` is set to true in `SchemaRegistryConfig` or `ExecutionConfig` if you want format violations to fail validation, and that your schemas avoid deeply nested `oneOf` or `anyOf` without an `if` and `then` short-circuit, because the validator must evaluate every branch and the resulting error messages become hard to read.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. networknt/json-schema-validator on GitHub
4. README
5. Releases