JsonSchema

public final classJsonSchema<T extends Object>

Definition of a data type.

These types can be objects, but also primitives and arrays. Represents a select subset of anJsonSchema object.

Note: While optional, including adescription field in yourJsonSchema is strongly encouraged. The more information the model has about what it's expected to generate, the better the results.

Summary

Nested types

public static classJsonSchema.Companion

Public methods

static final @NonNullJsonSchema<@NonNullString>

Returns aJsonSchema representing a value that must conform toany (one of) the provided sub-schema.

static final @NonNullJsonSchema<@NonNullList<@NonNull T>>
<T extends Object>array(
    @NonNullJsonSchema<@NonNull T> items,
    String description,
    boolean nullable,
    String title,
    Integer minItems,
    Integer maxItems
)

Returns aJsonSchema for an array.

static final @NonNullJsonSchema<@NonNullBoolean>
boolean(String description, boolean nullable, String title)

Returns aJsonSchema representing a boolean value.

static final @NonNullJsonSchema<@NonNullDouble>
double(
    String description,
    boolean nullable,
    String title,
    Double minimum,
    Double maximum
)

Returns aJsonSchema for a double-precision floating-point number.

static final @NonNullJsonSchema<@NonNullString>
enumeration(
    @NonNullList<@NonNullString> values,
    String description,
    boolean nullable,
    String title
)

Returns aJsonSchema for an enumeration.

static final @NonNullJsonSchema<@NonNull T>
<T extends Object>enumeration(
    @NonNullList<@NonNullString> values,
    @NonNullKClass<@NonNull T> clazz,
    String description,
    boolean nullable,
    String title
)

Returns aJsonSchema for an enumeration.

static final @NonNullJsonSchema<@NonNullFloat>
float(
    String description,
    boolean nullable,
    String title,
    Double minimum,
    Double maximum
)

Returns aJsonSchema for a single-precision floating-point number.

final @NonNullKSerializer<@NonNull T>
static final @NonNullJsonSchema<@NonNullInteger>
integer(
    String description,
    boolean nullable,
    String title,
    Double minimum,
    Double maximum
)

Returns aJsonSchema for a 32-bit signed integer number.

static final @NonNullJsonSchema<@NonNullLong>
long(
    String description,
    boolean nullable,
    String title,
    Double minimum,
    Double maximum
)

Returns aJsonSchema for a 64-bit signed integer number.

static final @NonNullJsonSchema<@NonNullJsonObject>
obj(
    @NonNullMap<@NonNullString, @NonNullJsonSchema<@NonNull ?>> properties,
    @NonNullList<@NonNullString> optionalProperties,
    String description,
    boolean nullable,
    String title
)

Returns aJsonSchema for a complex data type.

static final @NonNullJsonSchema<@NonNull T>
<T extends Object>obj(
    @NonNullMap<@NonNullString, @NonNullJsonSchema<@NonNull ?>> properties,
    @NonNullKClass<@NonNull T> clazz,
    @NonNullList<@NonNullString> optionalProperties,
    String description,
    boolean nullable,
    String title
)

Returns aJsonSchema for a complex data type.

static final @NonNullJsonSchema<@NonNullString>
string(
    String description,
    boolean nullable,
    StringFormat format,
    String title
)

Returns aJsonSchema for a string.

Public fields

anyOf

public final List<@NonNullJsonSchema<@NonNull ?>> anyOf

clazz

public final @NonNullKClass<@NonNull T> clazz

description

public final String description

enum

public final List<@NonNullString> enum

format

public final String format

items

public final JsonSchema<@NonNull ?> items

maxItems

public final Integer maxItems

maximum

public final Double maximum

minItems

public final Integer minItems

minimum

public final Double minimum

nullable

public final Boolean nullable

properties

public final Map<@NonNullString, @NonNullJsonSchema<@NonNull ?>> properties

required

public final List<@NonNullString> required

title

public final String title

type

public final @NonNullString type

Public methods

anyOf

public static final @NonNullJsonSchema<@NonNullString> anyOf(@NonNullList<@NonNullJsonSchema<@NonNull ?>> schemas)

Returns aJsonSchema representing a value that must conform toany (one of) the provided sub-schema.

Example: A field that can hold either a simple userID or a more detailed user object.

JsonSchema.anyOf( listOf( JsonSchema.integer(description = "User ID"), JsonSchema.obj( mapOf(
    "userID" to JsonSchema.integer(description = "User ID"),
    "username" to JsonSchema.string(description = "Username")
)))
Parameters
@NonNullList<@NonNullJsonSchema<@NonNull ?>> schemas

The list of valid schemas which could be here

array

public static final @NonNullJsonSchema<@NonNullList<@NonNull T>> <T extends Object>array(
    @NonNullJsonSchema<@NonNull T> items,
    String description,
    boolean nullable,
    String title,
    Integer minItems,
    Integer maxItems
)

Returns aJsonSchema for an array.

Parameters
@NonNullJsonSchema<@NonNull T> items

TheJsonSchema of the elements stored in the array.

String description

An optional description of what the array represents.

boolean nullable

Indicates whether the value can benull. Defaults tofalse.

boolean

public static final @NonNullJsonSchema<@NonNullBoolean> boolean(String description, boolean nullable, String title)

Returns aJsonSchema representing a boolean value.

Parameters
String description

An optional description of what the boolean should contain or represent.

boolean nullable

Indicates whether the value can benull. Defaults tofalse.

double

public static final @NonNullJsonSchema<@NonNullDouble> double(
    String description,
    boolean nullable,
    String title,
    Double minimum,
    Double maximum
)

Returns aJsonSchema for a double-precision floating-point number.

Parameters
String description

An optional description of what the number should contain or represent.

boolean nullable

Indicates whether the value can benull. Defaults tofalse.

enumeration

public static final @NonNullJsonSchema<@NonNullString> enumeration(
    @NonNullList<@NonNullString> values,
    String description,
    boolean nullable,
    String title
)

Returns aJsonSchema for an enumeration.

For example, the cardinal directions can be represented as:

JsonSchema.enumeration(listOf("north","east","south","west"),"Cardinal directions")
Parameters
@NonNullList<@NonNullString> values

The list of valid values for this enumeration

String description

The description of what the parameter should contain or represent

boolean nullable

Indicates whether the value can benull. Defaults tofalse.

enumeration

public static final @NonNullJsonSchema<@NonNull T> <T extends Object>enumeration(
    @NonNullList<@NonNullString> values,
    @NonNullKClass<@NonNull T> clazz,
    String description,
    boolean nullable,
    String title
)

Returns aJsonSchema for an enumeration.

For example, the cardinal directions can be represented as:

JsonSchema.enumeration(
listOf("north","east","south","west"),
Direction::class,
"Cardinal directions"
)
Parameters
@NonNullList<@NonNullString> values

The list of valid values for this enumeration

@NonNullKClass<@NonNull T> clazz

the real class that this schema represents

String description

The description of what the parameter should contain or represent

boolean nullable

Indicates whether the value can benull. Defaults tofalse.

float

public static final @NonNullJsonSchema<@NonNullFloat> float(
    String description,
    boolean nullable,
    String title,
    Double minimum,
    Double maximum
)

Returns aJsonSchema for a single-precision floating-point number.

Important: ThisJsonSchema provides a hint to the model that it should generate a single-precision floating-point number, but only guarantees that the value will be a number. Therefore it'spossible that decoding it as aFloat variable (orfloat in Java) could overflow.

Parameters
String description

An optional description of what the number should contain or represent.

boolean nullable

Indicates whether the value can benull. Defaults tofalse.

getSerializer

public final @NonNullKSerializer<@NonNull T> getSerializer()

integer

public static final @NonNullJsonSchema<@NonNullInteger> integer(
    String description,
    boolean nullable,
    String title,
    Double minimum,
    Double maximum
)

Returns aJsonSchema for a 32-bit signed integer number.

Important: ThisJsonSchema provides a hint to the model that it should generate a 32-bit integer, but only guarantees that the value will be an integer. Therefore it'spossible that decoding it as anInt variable (orint in Java) could overflow.

Parameters
String description

An optional description of what the integer should contain or represent.

boolean nullable

Indicates whether the value can benull. Defaults tofalse.

long

public static final @NonNullJsonSchema<@NonNullLong> long(
    String description,
    boolean nullable,
    String title,
    Double minimum,
    Double maximum
)

Returns aJsonSchema for a 64-bit signed integer number.

Parameters
String description

An optional description of what the number should contain or represent.

boolean nullable

Indicates whether the value can benull. Defaults tofalse.

obj

public static final @NonNullJsonSchema<@NonNullJsonObject> obj(
    @NonNullMap<@NonNullString, @NonNullJsonSchema<@NonNull ?>> properties,
    @NonNullList<@NonNullString> optionalProperties,
    String description,
    boolean nullable,
    String title
)

Returns aJsonSchema for a complex data type.

This schema instructs the model to produce data of type object, which has keys of typeString and values of typeJsonSchema.

Example: Acity could be represented with the following objectJsonSchema.

JsonSchema.obj(mapOf(
  "name"  to JsonSchema.string(),
  "population" to JsonSchema.integer()
))
Parameters
@NonNullMap<@NonNullString, @NonNullJsonSchema<@NonNull ?>> properties

The map of the object's property names to theirJsonSchemas.

@NonNullList<@NonNullString> optionalProperties

The list of optional properties. They must correspond to the keys provided in theproperties map. By default it's empty, signaling the model that all properties are to be included.

String description

An optional description of what the object represents.

boolean nullable

Indicates whether the value can benull. Defaults tofalse.

obj

public static final @NonNullJsonSchema<@NonNull T> <T extends Object>obj(
    @NonNullMap<@NonNullString, @NonNullJsonSchema<@NonNull ?>> properties,
    @NonNullKClass<@NonNull T> clazz,
    @NonNullList<@NonNullString> optionalProperties,
    String description,
    boolean nullable,
    String title
)

Returns aJsonSchema for a complex data type.

This schema instructs the model to produce data of type object, which has keys of typeString and values of typeJsonSchema.

Example: Acity could be represented with the following objectJsonSchema.

JsonSchema.obj(mapOf(
    "name"  to JsonSchema.string(),
    "population" to JsonSchema.integer()
  ),
  City::class
)
Parameters
@NonNullMap<@NonNullString, @NonNullJsonSchema<@NonNull ?>> properties

The map of the object's property names to theirJsonSchemas.

@NonNullKClass<@NonNull T> clazz

the real class that this schema represents

@NonNullList<@NonNullString> optionalProperties

The list of optional properties. They must correspond to the keys provided in theproperties map. By default it's empty, signaling the model that all properties are to be included.

String description

An optional description of what the object represents.

boolean nullable

Indicates whether the value can benull. Defaults tofalse.

string

public static final @NonNullJsonSchema<@NonNullString> string(
    String description,
    boolean nullable,
    StringFormat format,
    String title
)

Returns aJsonSchema for a string.

Parameters
String description

An optional description of what the string should contain or represent.

boolean nullable

Indicates whether the value can benull. Defaults tofalse.

StringFormat format

An optional pattern that values need to adhere to.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-06 UTC.