JsonSchema

public final class JsonSchema<T extends Object>

Definition of a data type.

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

Note: While optional, including a description field in your JsonSchema 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 class JsonSchema.Companion

Public fields
final List<@NonNull JsonSchema<@NonNull ?>>
final @NonNull KClass<@NonNull T>
final String
final List<@NonNull String>
final String
final JsonSchema<@NonNull ?>
final Integer
final Double
final Integer
final Double
final Boolean
final Map<@NonNull String, @NonNull JsonSchema<@NonNull ?>>
final List<@NonNull String>
final String
final @NonNull String

Public methods
static final @NonNull JsonSchema<@NonNull String>

Returns a JsonSchema representing a value that must conform to any (one of) the provided sub-schema.
static final @NonNull JsonSchema<@NonNull List<@NonNull T>>
<T extends Object> array(
    @NonNull JsonSchema<@NonNull T> items,
    String description,
    boolean nullable,
    String title,
    Integer minItems,
    Integer maxItems
)

Returns a JsonSchema for an array.
static final @NonNull JsonSchema<@NonNull Boolean>
boolean(String description, boolean nullable, String title)

Returns a JsonSchema representing a boolean value.
static final @NonNull JsonSchema<@NonNull Double>
double(
    String description,
    boolean nullable,
    String title,
    Double minimum,
    Double maximum
)

Returns a JsonSchema for a double-precision floating-point number.
static final @NonNull JsonSchema<@NonNull String>
enumeration(
    @NonNull List<@NonNull String> values,
    String description,
    boolean nullable,
    String title
)

Returns a JsonSchema for an enumeration.
static final @NonNull JsonSchema<@NonNull T>
<T extends Object> enumeration(
    @NonNull List<@NonNull String> values,
    @NonNull KClass<@NonNull T> clazz,
    String description,
    boolean nullable,
    String title
)

Returns a JsonSchema for an enumeration.
static final @NonNull JsonSchema<@NonNull Float>
float(
    String description,
    boolean nullable,
    String title,
    Double minimum,
    Double maximum
)

Returns a JsonSchema for a single-precision floating-point number.
final @NonNull KSerializer<@NonNull T>
static final @NonNull JsonSchema<@NonNull Integer>
integer(
    String description,
    boolean nullable,
    String title,
    Double minimum,
    Double maximum
)

Returns a JsonSchema for a 32-bit signed integer number.
static final @NonNull JsonSchema<@NonNull Long>
long(
    String description,
    boolean nullable,
    String title,
    Double minimum,
    Double maximum
)

Returns a JsonSchema for a 64-bit signed integer number.
static final @NonNull JsonSchema<@NonNull JsonObject>
obj(
    @NonNull Map<@NonNull String, @NonNull JsonSchema<@NonNull ?>> properties,
    @NonNull List<@NonNull String> optionalProperties,
    String description,
    boolean nullable,
    String title
)

Returns a JsonSchema for a complex data type.
static final @NonNull JsonSchema<@NonNull T>
<T extends Object> obj(
    @NonNull Map<@NonNull String, @NonNull JsonSchema<@NonNull ?>> properties,
    @NonNull KClass<@NonNull T> clazz,
    @NonNull List<@NonNull String> optionalProperties,
    String description,
    boolean nullable,
    String title
)

Returns a JsonSchema for a complex data type.
static final @NonNull JsonSchema<@NonNull String>
string(
    String description,
    boolean nullable,
    StringFormat format,
    String title
)

Returns a JsonSchema for a string.

Public fields

anyOf

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

clazz

public final @NonNull KClass<@NonNull T> clazz

description

public final String description

enum

public final List<@NonNull String> 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<@NonNull String, @NonNull JsonSchema<@NonNull ?>> properties

required

public final List<@NonNull String> required

title

public final String title

type

public final @NonNull String type

Public methods

anyOf

public static final @NonNull JsonSchema<@NonNull String> anyOf(@NonNull List<@NonNull JsonSchema<@NonNull ?>> schemas)

Returns a JsonSchema representing a value that must conform to any (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
@NonNull List<@NonNull JsonSchema<@NonNull ?>> schemas

The list of valid schemas which could be here

array

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

Returns a JsonSchema for an array.

Parameters
@NonNull JsonSchema<@NonNull T> items

The JsonSchema of the elements stored in the array.
String description

An optional description of what the array represents.
boolean nullable

Indicates whether the value can be null. Defaults to false.

boolean

public static final @NonNull JsonSchema<@NonNull Boolean> boolean(String description, boolean nullable, String title)

Returns a JsonSchema 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 be null. Defaults to false.

double

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

Returns a JsonSchema 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 be null. Defaults to false.

enumeration

public static final @NonNull JsonSchema<@NonNull String> enumeration(
    @NonNull List<@NonNull String> values,
    String description,
    boolean nullable,
    String title
)

Returns a JsonSchema for an enumeration.

For example, the cardinal directions can be represented as:

JsonSchema.enumeration(listOf("north", "east", "south", "west"), "Cardinal directions")
Parameters
@NonNull List<@NonNull String> 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 be null. Defaults to false.

enumeration

public static final @NonNull JsonSchema<@NonNull T> <T extends Object> enumeration(
    @NonNull List<@NonNull String> values,
    @NonNull KClass<@NonNull T> clazz,
    String description,
    boolean nullable,
    String title
)

Returns a JsonSchema for an enumeration.

For example, the cardinal directions can be represented as:

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

The list of valid values for this enumeration
@NonNull KClass<@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 be null. Defaults to false.

float

public static final @NonNull JsonSchema<@NonNull Float> float(
    String description,
    boolean nullable,
    String title,
    Double minimum,
    Double maximum
)

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

Important: This JsonSchema 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's possible that decoding it as a Float variable (or float 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 be null. Defaults to false.

getSerializer

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

integer

public static final @NonNull JsonSchema<@NonNull Integer> integer(
    String description,
    boolean nullable,
    String title,
    Double minimum,
    Double maximum
)

Returns a JsonSchema for a 32-bit signed integer number.

Important: This JsonSchema 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's possible that decoding it as an Int variable (or int 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 be null. Defaults to false.

long

public static final @NonNull JsonSchema<@NonNull Long> long(
    String description,
    boolean nullable,
    String title,
    Double minimum,
    Double maximum
)

Returns a JsonSchema 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 be null. Defaults to false.

obj

public static final @NonNull JsonSchema<@NonNull JsonObject> obj(
    @NonNull Map<@NonNull String, @NonNull JsonSchema<@NonNull ?>> properties,
    @NonNull List<@NonNull String> optionalProperties,
    String description,
    boolean nullable,
    String title
)

Returns a JsonSchema for a complex data type.

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

Example: A city could be represented with the following object JsonSchema.

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

The map of the object's property names to their JsonSchemas.
@NonNull List<@NonNull String> optionalProperties

The list of optional properties. They must correspond to the keys provided in the properties 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 be null. Defaults to false.

obj

public static final @NonNull JsonSchema<@NonNull T> <T extends Object> obj(
    @NonNull Map<@NonNull String, @NonNull JsonSchema<@NonNull ?>> properties,
    @NonNull KClass<@NonNull T> clazz,
    @NonNull List<@NonNull String> optionalProperties,
    String description,
    boolean nullable,
    String title
)

Returns a JsonSchema for a complex data type.

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

Example: A city could be represented with the following object JsonSchema.

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

The map of the object's property names to their JsonSchemas.
@NonNull KClass<@NonNull T> clazz

the real class that this schema represents
@NonNull List<@NonNull String> optionalProperties

The list of optional properties. They must correspond to the keys provided in the properties 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 be null. Defaults to false.

string

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

Returns a JsonSchema for a string.

Parameters
String description

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

Indicates whether the value can be null. Defaults to false.
StringFormat format

An optional pattern that values need to adhere to.