jsonschema-generator: JSON Schema drafts straight from your Java classes

A schema derived from the class, not written beside it

The victools jsonschema-generator creates JSON Schema from your Java classes, and the README states the supported drafts plainly: Draft 6, Draft 7, Draft 2019-09 and Draft 2020-12.

The problem it solves is the one every JSON API team hits. You have a DTO, a request object or a record type, and somewhere a schema file has to describe it for a consumer, a validator, a documentation page or a code generator. Written by hand, the schema and the class drift apart within a release cycle, and then the schema is the thing that is wrong.

Generating the schema from the class makes the class the single source of truth, and the important qualifier is that it is a derived artefact rather than a hand maintained contract. The generated schema describes what the class is. If the wire format is meant to be a stable public contract that outlives internal refactoring, the class and the schema will both move with the code, and whether that is a feature or a problem depends on what you promised your consumers.

The implementation uses Jackson, and that choice is visible in the code rather than hidden. The example in the README imports tools.jackson.databind.JsonNode, and the result of a generation is a Jackson node that you can print with toPrettyString.

The audience is Java developers who need a schema artefact out of their type definitions, and the project is Apache-2.0 licensed, with the documentation hosted at victools.github.io/jsonschema-generator and the code on Maven Central as com.github.victools:jsonschema-generator.

A config builder, a generator and one method call

The minimal example is short enough to memorise, and it shows the shape of the whole API.

SchemaGeneratorConfigBuilder configBuilder = new SchemaGeneratorConfigBuilder(SchemaVersion.DRAFT_2020_12, OptionPreset.PLAIN_JSON);
SchemaGeneratorConfig config = configBuilder.build();
SchemaGenerator generator = new SchemaGenerator(config);
JsonNode jsonSchema = generator.generateSchema(YourClass.class);

System.out.println(jsonSchema.toPrettyString());

Three objects and a call. The config builder takes a schema version, here DRAFT_2020_12, and an option preset, here PLAIN_JSON, and produces an immutable config. The generator holds that config, and generateSchema takes a class and returns a JSON node. The result is a Jackson tree, so it composes with the rest of a Jackson based application, and it can be written out, diffed or embedded in a larger document.

The two arguments to the builder are the interesting part, because they are the two axes of behaviour. The version selects the draft, and the preset selects how much annotation driven behaviour is on by default. A plain preset gives you the schema derived from the class shape, and the modules described later add the constraints that live in your annotations.

That separation between a base generator and annotation reading modules is the design idea of the whole project, and it is why the README splits the modules out as separate artefacts rather than folding them into the core.

Additional examples live in the jsonschema-examples folder and throughout the test classes, which is a useful pointer for the options that are not in the quick start.

The modules are where the annotations become constraints

The core generator is only the first of the artefacts the project publishes, and the modules are what turn an annotated class into an accurate schema.

The jackson module derives schema attributes from Jackson annotations, for example the description, property name overrides and which properties to ignore, and it also looks up appropriate annotated subtypes. That last part is the subtle one, because a property declared as an interface or a base class cannot be fully described without knowing which concrete type the object will hold at runtime, and the module resolves that from the annotations.

The jakarta-validation and javax-validation modules do the same job for validation constraints: which properties are nullable, their minimum and maximum, their minItems and maxItems, and their minLength and maxLength. There are two of them because Jakarta Validation and javax Validation are different annotation packages, and a project on either can use the matching module without changing its own code.

The swagger modules cover the older Swagger annotations, 1.5 and 2, and the 1.5 module adds const and enum handling. The swagger-2 module derives attributes from the 2.x @Schema annotation.

There is also a Maven plugin, victools/jsonschema-maven-plugin, which generates JSON Schemas as part of your Maven build, and a module example outside the project, imIfOu/jsonschema-module-addon, which derives schema attributes from a custom annotation with various parameters.

That last example is the intended extension path. If the constraint you need is not in any shipped module, the answer is not to fork the generator, it is to write a module that reads your annotation, and the project documents that as a supported route rather than an accident.

Mixed versions fail at runtime, not at compile time

The README has a short but emphatic note on versions, and it is the one piece of operational advice in the documentation.

Since version 4.7, the release versions of the main generator library and the standard modules are aligned, and it is recommended to use identical versions for all of them to ensure compatibility.

Then the warning: it is discouraged to use an older or lower jsonschema-generator version than any of your jsonschema-module dependencies, because if the module uses a feature that was only added to the generator in the newer version, runtime errors are to be expected.

The failure mode explains the emphasis. A module compiled against a newer generator API and run against an older one does not necessarily fail at build time, it fails when the code path is exercised, which in a schema generation step is often in a test or in a build step rather than in the application that consumes the schema. That is an expensive class of bug to diagnose, and the cheap prevention is to align the versions.

For a Maven project the practical mechanism for this is the bill of materials artefact, jsonschema-generator-bom, which lets a project import one version for the generator and all of the modules instead of repeating versions in each dependency declaration.

Version 5 moves the stack to Jackson 3 and Java 17

The release history shows the moment the project changed its foundations.

v4.37.0 is described as dependency updates, bug fixes and minor features and is dated 2024-11-11. v4.38.0, described as a minor improvement and bug fix, is dated 2025-03-24. And v5.0.0 is titled Jackson 3 and Java 17, dated 2026-02-10.

That is a major version bump for a reason that has nothing to do with the generator's own API. The 5.x line requires Java 17 and moves from the com.fasterxml.jackson namespace to the tools.jackson one, which is the Jackson 3 package structure. The import in the README's own example, tools.jackson.databind.JsonNode, is the proof of it.

For a team already on Jackson 3, that removes an awkward choice, because the schema output is a Jackson tree and mixing Jackson 2 and Jackson 3 trees in one application is unpleasant. For a team still on Jackson 2, the choice is between staying on the 4.x line, which the compatibility table shows working with the earlier Agda-style version pinning approach, and doing the Jackson migration as part of taking the new generator.

The build tooling in the repository root is unremarkable and correct: a parent pom, a checkstyle configuration, a CHANGELOG, a slate-docs directory for the documentation site, and the per-module directories that match the artefacts on Maven Central.

What the generator cannot tell you, and the alternative of writing the schema yourself

It is worth being clear about the boundary of this tool, because the name suggests more than it does.

The generator produces a schema from classes. It does not validate anything. A schema and a validator are different artefacts with different jobs, and while a schema can be fed to a validator elsewhere, the generator's output is not itself a check on incoming data. If your problem is rejecting bad requests, this library is a step earlier in the pipeline than the one you need.

It also cannot describe a contract that your classes do not express. If the JSON you send is a view of the domain model rather than the domain model itself, with renamed fields, flattened structures or computed values, then the schema has to be written or the class has to be shaped to match, and the second of those is usually the wrong trade.

That is where the alternative approach earns its place. Hand written schemas, or a schema maintained separately from the classes, let you fix a public contract and let the internals move freely underneath it, at the cost of keeping the two in step by hand. Generating from classes does the opposite, and is the better choice when the class is the contract.

A third option is the runtime validation libraries, which check instances against annotations rather than producing a schema. Those answer a different question, and combining them with a generator is a common and sensible arrangement, since the same annotations feed both.

Editorial conclusion

jsonschema-generator suits a Java team whose API contract is a set of classes and who want the schema to follow the code, especially when those classes already carry Jackson, Jakarta Validation or Swagger annotations that describe the wire format. It does not suit a project where the JSON contract is deliberately different from the internal model, because the generator can only describe what the classes describe. Check three things before you adopt it: that you pin one version across the generator and every module, since the README warns that mismatched versions cause runtime errors, that your Jackson major version matches the generator line you take, with the 5.x line on Jackson 3 and Java 17, and that the module set you need actually exists, because a constraint only appears in the schema if a module reads the annotation that carries it. The last push to the repository was on 2026-06-23 and the newest release is v5.0.0 from 2026-02-10.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. victools/jsonschema-generator on GitHub