JSON-Schema Support

Juneau provides the JsonSchemaSerializer class for generating JSON-Schema documents that describe the output generated by the JsonSerializer class. This class shares the same properties as JsonSerializer.

For convenience the JsonSerializer.getSchemaSerializer() method has been added for creating instances of schema serializers from the regular serializer instance.

When you want a typed schema DTO instead of raw map output, use JsonSchemaBeanGenerator from juneau-bean-jsonschema:

import org.apache.juneau.bean.jsonschema.*;

JsonSchema schema = JsonSchemaBeanGenerator.DEFAULT.generate(Person.class);
// Equivalent convenience:
JsonSchema<?> schema2 = JsonSchema.of(Person.class);

Schema Validation

Parsers and serializers can also enforce @Schema constraints at parse/serialize time by enabling MarshallingContext.Builder.validateSchema(). Validation is powered by JsonSchemaValidator in juneau-bean-jsonschema, which implements JSON Schema Draft 2020-12 semantics over the typed JsonSchema bean. See juneau-bean-jsonschema for details and supported keywords.

Sample Beans

public class Person {

    // Bean properties
    public String name;
    public Calendar birthDate;
    public List addresses;

    // Getters/setters omitted
}

public class Address {

    // Bean properties
    public String street, city;
    public StateEnum state;
    public int zip;
    public boolean isCurrent;

    // Getters/setters omitted
}

The code for creating our POJO model and generating JSON-Schema is shown below:

// Get the one of the default schema serializers.
JsonSchemaSerializer serializer = JsonSchemaSerializer.DEFAULT_SIMPLE_READABLE;

// Get the JSON Schema for the POJO.
String jsonSchema = serializer.write(new Person());

// This also works.
jsonSchema = serializer.write(Person.class);

JSON Schema

{
    type: 'object',
    description: 'org.apache.juneau.sample.Person',
    properties: {
        name: {
            type: 'string',
            description: 'java.lang.String'
        },
        birthDate: {
            type: 'string',
            description: 'java.util.Calendar'
        },
        addresses: {
            type: 'array',
            description: 'java.util.LinkedList',
            items: {
                type: 'object',
                description: 'org.apache.juneau.sample.Address',
                properties: {
                    street: {
                        type: 'string',
                        description: 'java.lang.String'
                    },
                    city: {
                        type: 'string',
                        description: 'java.lang.String'
                    },
                    state: {
                        type: 'string',
                        description: 'java.lang.String'
                    },
                    zip: {
                        type: 'number',
                        description: 'int'
                    },
                    isCurrent: {
                        type: 'boolean',
                        description: 'boolean'
                    }
                }
            }
        }
    }
}

AI-friendly summary

The @Schema annotation supports a summary field (alias su) for short, single-line descriptions intended for AI / LLM consumption, compact docs, and tooltips. Unlike description, which can be multi-line and detailed, summary should be a single sentence or phrase that captures the essential meaning.

@Schema(
    summary="A pet available for adoption",
    description={
        "Represents a pet in the store's inventory.",
        "Includes details such as name, species, breed, age, and adoption status."
    }
)
public class Pet {

    @Schema(summary="The pet's display name")
    public String name;
}

The summary value is emitted under the JSON Schema key "summary" and is also propagated through JsonSchemaBeanGenerator (accessible via JsonSchema.getSummary()) and into generated Swagger / OpenAPI documents. The companion annotations @Marshalled, @BeanProp, @Response, @Header, @Query, @Path, @FormData, and @Content expose a matching summary field.