JSON Schema
Overview
JSON Schema is a specification for describing the structure and validation rules of JSON data. It lets you define what properties are required, their types, allowed values, and more. By using JSON Schema, you can validate that incoming or outgoing JSON matches the expected contract, provide clear documentation for APIs, and enable tooling support such as code generation and auto-completion.
Helidon provides two complementary ways to work with JSON Schema.
- In the declarative approach, you describe the schema using annotations in a
JsonSchemaclass. - In the imperative approach, you build the schema programmatically with the
fluent
Schemabuilder API.
Helidon currently supports only schema generation.
Maven Coordinates
To enable JSON Schema, add the following dependency to your project’s pom.xml
(see Managing Dependencies).
<dependency>
<groupId>io.helidon.json.schema</groupId>
<artifactId>helidon-json-schema</artifactId>
</dependency>
Usage
Imperative Schema Creation
The entry point for each runtime JSON schema creation is a Schema
class. The imperative approach gives you full programmatic control over JSON
Schema creation. Using the fluent Schema builder API, you can construct schemas
step by step, configure properties, and apply constraints directly in code. This
is useful when schemas need to be generated dynamically or when fine-grained
customization is required.
Schema.builder()
.rootObject(builder -> builder.description("Example JSON Schema")
.addIntegerProperty("exampleProperty", intBuilder -> intBuilder.minimum(0)))
.build();
Once the Schema object is created, you can generate the JSON Schema
as a String. The result looks like this:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "Example JSON Schema",
"type": "object",
"properties": {
"exampleProperty": {
"type": "integer",
"minimum": 0
}
}
}
Declarative Schema Creation
The declarative approach lets you define JSON Schema through annotations in a
JsonSchema class. At compile time, the
helidon-json-schema-codegen generator processes these annotations and produces
a class containing the schema definition. This approach keeps your schema
definitions close to your data model and ensures schemas are generated
automatically without manual coding.
In addition, the following section must be added to the build of the Maven
pom.xml to enable annotation processors that generate the necessary code:
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<annotationProcessorPaths>
<path>
<groupId>io.helidon.bundles</groupId>
<artifactId>helidon-bundles-apt</artifactId>
<version>${helidon.version}</version>
</path>
</annotationProcessorPaths>
</configuration>
</plugin>
</plugins>
Once compiled, the class with the following name will be generated
ExampleSchema__JsonSchema. This class contains the String format of the schema
and is automatically discovered via ServiceRegistry. Because of that, it is
possible to inject the Schema with the
@Service.Named and desired class (such as
ExampleSchema.class) as a value.
public void myMethod(@Service.Named(ExampleSchema.class) Schema schema) {
//...
}
Or obtain it over the static find method on the Schema class. This
methods searches the ServiceRegistry for a Schema bound to the provided class
over the parameter.
Schema.find(MyClass.class);
Enum and Date/Time Properties
For record and model properties, schema generation infers the following string
schemas. An enum annotated with @JsonSchema.Schema can also define a root
schema, using the enum constant names as its allowed values.
| Java type | Generated JSON Schema |
|---|---|
| Enum | type: "string", with enum containing the constant names in declaration order |
LocalDate | type: "string", format: "date" |
Instant | type: "string", format: "date-time" |
LocalDateTime, LocalTime, OffsetDateTime, OffsetTime, ZonedDateTime, Duration, Period | type: "string", without an inferred format |
The date and date-time formats describe the usual four-digit-year values.
The other listed date/time types do not infer a standard format: depending on
the type, Java's string representation can omit seconds or an offset, include
a zone ID, or represent an amount of time instead of a date or time.
Custom schema providers can use the SchemaString builder methods
format(String), enumValues(List<JsonValue>), and addEnumValue(JsonValue) to
describe their schema. The addEnumValue(String) overload adds a JSON string.
Schema parsing and generation preserve format and every enum entry, including
JSON null, numbers, booleans, objects, and arrays. Entries retain their JSON types
and declaration order; they are not converted to strings or discarded.
The type: "string" constraint still applies independently when validating an
instance. An absent enum imposes no enum restriction; an explicit empty enum
array allows no values.
This metadata describes the JSON contract; it does not validate values or add
serialization support for Java types.