Schema

public final class Schema

Definition of a data type.

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

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

Public fields
final String
final List<@NonNull String>
final String
final Schema
final Boolean
final Map<@NonNull String, @NonNull Schema>
final List<@NonNull String>
final @NonNull String

Public methods
static final @NonNull Schema
array(@NonNull Schema items, String description, boolean nullable)

Returns a Schema for an array.
static final @NonNull Schema
boolean(String description, boolean nullable)

Returns a Schema representing a boolean value.
static final @NonNull Schema
double(String description, boolean nullable)

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

Returns a Schema for an enumeration.
static final @NonNull Schema
float(String description, boolean nullable)

Returns a Schema for a single-precision floating-point number.
static final @NonNull Schema
integer(String description, boolean nullable)

Returns a Schema for a 32-bit signed integer number.
static final @NonNull Schema
long(String description, boolean nullable)

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

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

Returns a Schema for a string.

Public fields

description

public final String description

enum

public final List<@NonNull String> enum

format

public final String format

items

public final Schema items

nullable

public final Boolean nullable

properties

public final Map<@NonNull String, @NonNull Schema> properties

required

public final List<@NonNull String> required

type

public final @NonNull String type

Public methods

array

public static final @NonNull Schema array(@NonNull Schema items, String description, boolean nullable)

Returns a Schema for an array.

Parameters
@NonNull Schema items

The Schema 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 Schema boolean(String description, boolean nullable)

Returns a Schema 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 Schema double(String description, boolean nullable)

Returns a Schema 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 Schema enumeration(
    @NonNull List<@NonNull String> values,
    String description,
    boolean nullable
)

Returns a Schema for an enumeration.

For example, the cardinal directions can be represented as:

Schema.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.

float

public static final @NonNull Schema float(String description, boolean nullable)

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

Important: This Schema 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.

integer

public static final @NonNull Schema integer(String description, boolean nullable)

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

Important: This Schema 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 Schema long(String description, boolean nullable)

Returns a Schema 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 Schema obj(
    @NonNull Map<@NonNull String, @NonNull Schema> properties,
    @NonNull List<@NonNull String> optionalProperties,
    String description,
    boolean nullable
)

Returns a Schema 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 Schema.

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

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

The map of the object's property names to their Schemas.
@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 Schema string(String description, boolean nullable, StringFormat format)

Returns a Schema 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.