IMPORTANT: In July 2025, we stopped releasing new versions of KTX modules, and we removed the KTX libraries from the Firebase Android BoM (v34.0.0). If you use KTX APIs from the previously released KTX modules, we recommend that you migrate your app to use KTX APIs from the main modules instead. For details, see the FAQ about this initiative.

JsonSchema

class JsonSchema<T : Any>

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

Public companion functions
`JsonSchema<String>`	`anyOf(schemas: List<JsonSchema<>>)` Returns a `JsonSchema` representing a value that must conform to any* (one of) the provided sub-schema.
`JsonSchema<List<T>>`	`<T : Any> array( items: JsonSchema<T>, description: String?, nullable: Boolean, title: String?, minItems: Int?, maxItems: Int? )` Returns a `JsonSchema` for an array.
`JsonSchema<Boolean>`	`boolean(description: String?, nullable: Boolean, title: String?)` Returns a `JsonSchema` representing a boolean value.
`JsonSchema<Double>`	`double( description: String?, nullable: Boolean, title: String?, minimum: Double?, maximum: Double? )` Returns a `JsonSchema` for a double-precision floating-point number.
`JsonSchema<String>`	`enumeration( values: List<String>, description: String?, nullable: Boolean, title: String? )` Returns a `JsonSchema` for an enumeration.
`JsonSchema<T>`	`<T : Any> enumeration( values: List<String>, clazz: KClass<T>, description: String?, nullable: Boolean, title: String? )` Returns a `JsonSchema` for an enumeration.
`JsonSchema<Float>`	`float( description: String?, nullable: Boolean, title: String?, minimum: Double?, maximum: Double? )` Returns a `JsonSchema` for a single-precision floating-point number.
`JsonSchema<Int>`	`integer( description: String?, nullable: Boolean, title: String?, minimum: Double?, maximum: Double? )` Returns a `JsonSchema` for a 32-bit signed integer number.
`JsonSchema<Long>`	`long( description: String?, nullable: Boolean, title: String?, minimum: Double?, maximum: Double? )` Returns a `JsonSchema` for a 64-bit signed integer number.
`JsonSchema<JsonObject>`	`obj( properties: Map<String, JsonSchema<*>>, optionalProperties: List<String>, description: String?, nullable: Boolean, title: String? )` Returns a `JsonSchema` for a complex data type.
`JsonSchema<T>`	`<T : Any> obj( properties: Map<String, JsonSchema<*>>, clazz: KClass<T>, optionalProperties: List<String>, description: String?, nullable: Boolean, title: String? )` Returns a `JsonSchema` for a complex data type.
`JsonSchema<String>`	`string( description: String?, nullable: Boolean, format: StringFormat?, title: String? )` Returns a `JsonSchema` for a string.

Public functions
`KSerializer<T>`	`getSerializer()`

Public properties
`List<JsonSchema<*>>?`	`anyOf`
`KClass<T>`	`clazz`
`String?`	`description`
`List<String>?`	`enum`
`String?`	`format`
`JsonSchema<*>?`	`items`
`Int?`	`maxItems`
`Double?`	`maximum`
`Int?`	`minItems`
`Double?`	`minimum`
`Boolean?`	`nullable`
`Map<String, JsonSchema<*>>?`	`properties`
`List<String>?`	`required`
`String?`	`title`
`String`	`type`

Public companion functions

anyOf

fun anyOf(schemas: List<JsonSchema<*>>): JsonSchema<String>

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
`schemas: List<JsonSchema<*>>`	The list of valid schemas which could be here

array

fun <T : Any> array(
    items: JsonSchema<T>,
    description: String? = null,
    nullable: Boolean = false,
    title: String? = null,
    minItems: Int? = null,
    maxItems: Int? = null
): JsonSchema<List<T>>

Returns a JsonSchema for an array.

Parameters
`items: JsonSchema<T>`	The `JsonSchema` of the elements stored in the array.
`description: String? = null`	An optional description of what the array represents.
`nullable: Boolean = false`	Indicates whether the value can be `null`. Defaults to `false`.

boolean

fun boolean(description: String? = null, nullable: Boolean = false, title: String? = null): JsonSchema<Boolean>

Returns a JsonSchema representing a boolean value.

Parameters
`description: String? = null`	An optional description of what the boolean should contain or represent.
`nullable: Boolean = false`	Indicates whether the value can be `null`. Defaults to `false`.

double

fun double(
    description: String? = null,
    nullable: Boolean = false,
    title: String? = null,
    minimum: Double? = null,
    maximum: Double? = null
): JsonSchema<Double>

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

Parameters
`description: String? = null`	An optional description of what the number should contain or represent.
`nullable: Boolean = false`	Indicates whether the value can be `null`. Defaults to `false`.

enumeration

fun enumeration(
    values: List<String>,
    description: String? = null,
    nullable: Boolean = false,
    title: String? = null
): JsonSchema<String>

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
`values: List<String>`	The list of valid values for this enumeration
`description: String? = null`	The description of what the parameter should contain or represent
`nullable: Boolean = false`	Indicates whether the value can be `null`. Defaults to `false`.

enumeration

fun <T : Any> enumeration(
    values: List<String>,
    clazz: KClass<T>,
    description: String? = null,
    nullable: Boolean = false,
    title: String? = null
): JsonSchema<T>

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
`values: List<String>`	The list of valid values for this enumeration
`clazz: KClass<T>`	the real class that this schema represents
`description: String? = null`	The description of what the parameter should contain or represent
`nullable: Boolean = false`	Indicates whether the value can be `null`. Defaults to `false`.

float

fun float(
    description: String? = null,
    nullable: Boolean = false,
    title: String? = null,
    minimum: Double? = null,
    maximum: Double? = null
): JsonSchema<Float>

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
`description: String? = null`	An optional description of what the number should contain or represent.
`nullable: Boolean = false`	Indicates whether the value can be `null`. Defaults to `false`.

integer

fun integer(
    description: String? = null,
    nullable: Boolean = false,
    title: String? = null,
    minimum: Double? = null,
    maximum: Double? = null
): JsonSchema<Int>

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
`description: String? = null`	An optional description of what the integer should contain or represent.
`nullable: Boolean = false`	Indicates whether the value can be `null`. Defaults to `false`.

long

fun long(
    description: String? = null,
    nullable: Boolean = false,
    title: String? = null,
    minimum: Double? = null,
    maximum: Double? = null
): JsonSchema<Long>

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

Parameters
`description: String? = null`	An optional description of what the number should contain or represent.
`nullable: Boolean = false`	Indicates whether the value can be `null`. Defaults to `false`.

obj

fun obj(
    properties: Map<String, JsonSchema<*>>,
    optionalProperties: List<String> = emptyList(),
    description: String? = null,
    nullable: Boolean = false,
    title: String? = null
): JsonSchema<JsonObject>

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
`properties: Map<String, JsonSchema<*>>`	The map of the object's property names to their `JsonSchema`s.
`optionalProperties: List<String> = emptyList()`	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.
`description: String? = null`	An optional description of what the object represents.
`nullable: Boolean = false`	Indicates whether the value can be `null`. Defaults to `false`.

obj

fun <T : Any> obj(
    properties: Map<String, JsonSchema<*>>,
    clazz: KClass<T>,
    optionalProperties: List<String> = emptyList(),
    description: String? = null,
    nullable: Boolean = false,
    title: String? = null
): JsonSchema<T>

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
`properties: Map<String, JsonSchema<*>>`	The map of the object's property names to their `JsonSchema`s.
`clazz: KClass<T>`	the real class that this schema represents
`optionalProperties: List<String> = emptyList()`	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.
`description: String? = null`	An optional description of what the object represents.
`nullable: Boolean = false`	Indicates whether the value can be `null`. Defaults to `false`.

string

fun string(
    description: String? = null,
    nullable: Boolean = false,
    format: StringFormat? = null,
    title: String? = null
): JsonSchema<String>

Returns a JsonSchema for a string.

Parameters
`description: String? = null`	An optional description of what the string should contain or represent.
`nullable: Boolean = false`	Indicates whether the value can be `null`. Defaults to `false`.
`format: StringFormat? = null`	An optional pattern that values need to adhere to.

Public functions

getSerializer

fun getSerializer(): KSerializer<T>

Public properties

anyOf

val anyOf: List<JsonSchema<*>>?

clazz

val clazz: KClass<T>

description

val description: String?

enum

val enum: List<String>?

format

val format: String?

items

val items: JsonSchema<*>?

maxItems

val maxItems: Int?

maximum

val maximum: Double?

minItems

val minItems: Int?

minimum

val minimum: Double?

nullable

val nullable: Boolean?

properties

val properties: Map<String, JsonSchema<*>>?

required

val required: List<String>?

title

val title: String?

type

val type: String