JSON Schema

Helidon 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 JsonSchema class.
  • In the imperative approach, you build the schema programmatically with the fluent Schema builder 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).

pom.xml
<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.

@JsonSchema.Schema1
@JsonSchema.Description("Example JSON Schema")
public record ExampleSchema(@JsonSchema.Integer.Minimum(0) int exampleProperty) {
}
  1. Schema defining annotation. Without this annotation the class/record will not be processed as a JSON schema

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:

pom.xml
<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 typeGenerated JSON Schema
Enumtype: "string", with enum containing the constant names in declaration order
LocalDatetype: "string", format: "date"
Instanttype: "string", format: "date-time"
LocalDateTime, LocalTime, OffsetDateTime, OffsetTime, ZonedDateTime, Duration, Periodtype: "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.

Copyright © 2018, 2026 Oracle and/or its affiliates.