Skip to content
Untitled Sandbox - Developer Documentation
docs/api/schema

@usbx/schema

Check the shape of values

local schema = require("@usbx/schema")
booleanfunctionnumberfunctionstringfunctionvector3functioncolorfunctioninstancefunctionplayerfunctionoptionalfunctionarrayfunctionstructfunctionenumfunctionmapfunctionunionfunctionanyfunction

schema.boolean

function

Accepts a boolean.

schema.boolean() -> Schema<boolean>
example
local flag = schema.boolean()

Use it forstoring a true or false answer, like whether a player owns a pass or has finished the tutorial.

schema.number

function

Accepts a number.

schema.number(options: { … }?) -> Schema<number>
example
local level = schema.number({ min = 1, integer = true })

Use it forstoring tokens, levels or health, with a lowest and highest value if you want one.

optionsoptionalLimits on the number.
Build a number callmin · max · integer
  • min

    The lowest number the value is allowed to be.

  • max

    The highest number the value is allowed to be.

  • integer

    Set it to true to allow only whole numbers, so values with a decimal part are not accepted.

schema.string

function

Accepts a string.

schema.string(options: { … }?) -> Schema<string>
example
local nickname = schema.string({ max_length = 20 })

Use it forstoring a nickname or pet name, and keeping it under a length limit you choose.

optionsoptionalLimits on the text.
Build a string callmax_length
  • max_length

    The most characters the text is allowed to have.

schema.vector3

function

Accepts a vector.

schema.vector3() -> Schema<vector>
example
local spot = schema.vector3()

Use it forstoring a position, like a player's last checkpoint or where something should spawn.

schema.color

function

Accepts a color.

schema.color() -> Schema<Color>
example
local tint = schema.color()

Use it forstoring a color a player picked, like the paint on their car or their outfit.

schema.instance

function

Accepts an instance.

schema.instance(options: { … }?) -> Schema<Instance>
example
local target = schema.instance({ kind = "part" })

Use it forstoring which part or other instance is the current target or goal of a round.

optionsoptionalWhich kind of instance.
Build a instance callkind
  • kind

    Accepts only instances of this kind, so you give a kind name written the same way as the examples.

    for example

schema.player

function

Accepts a player.

schema.player() -> Schema<Player>
example
local owner = schema.player()

Use it forstoring who is "it" in a game of tag, or which player owns a shop.

schema.optional

function

Also accepts nil.

schema.optional<T>(schema: Schema<T>) -> Schema<T?>
example
local title = schema.optional(schema.string())

Use it forstoring something a player might not have yet, like a title, which stays nil until they earn it.

schemaWhat a value that is not nil must fit.

schema.array

function

Accepts a list.

schema.array<T>(schema: Schema<T>) -> Schema<{ T }>
example
local names = schema.array(schema.string())

Use it forstoring a list, like a player's inventory or the badges they have collected so far.

schemaWhat every item must fit.

schema.struct

function

Accepts a table with these fields. Luau cannot work out its type: name it, as in Schema<{ level: number }>.

schema.struct(fields: { [string]: Schema<any> }) -> Schema<any>
example
local stats: Schema<{ name: string, level: number }> = schema.struct({ name = schema.string(), level = schema.number({ min = 1 }) })

Use it forstoring several named values together, like a player's saved name, level and XP.

fieldsThe schema of each field, by name.

schema.enum

function

Accepts one of these strings. Luau cannot work out its type: name it, as in Schema<"easy" | "hard">.

schema.enum(values: { string }) -> Schema<any>
example
local mode: Schema<"easy" | "hard"> = schema.enum({ "easy", "hard" })

Use it forstoring a choice from a fixed list of words, like a difficulty or a game mode.

valuesThe strings it accepts.

schema.map

function

Accepts a table whose keys and values fit the schemas.

schema.map<K, V>(keys: Schema<K>, values: Schema<V>) -> Schema<{ [K]: V }>
example
local scores = schema.map(schema.string(), schema.number())

Use it forstoring scores by player name, or how many of each item a player has by item name.

keysWhat every key must fit.
valuesWhat every value must fit.

schema.union

function

Accepts a value that fits one of two or more schemas. Luau cannot work out its type: name it, as in Schema<string | number>.

schema.union(...Schema<any>) -> Schema<any>
example
local id = schema.union(schema.string(), schema.number())

Use it forstoring a value that can fit more than one schema, like an ID that is text or a number.

...optionalTwo or more schemas.

schema.any

function

Accepts any value, also nil.

schema.any() -> Schema<any>
example
local anything = schema.any()

Use it forstoring a value of any shape, with no checking.

↑ ↓ moveEnter openEsc close