Breadboard Type Expressions
Breadboard Type Expressions allow you to declare schemas for Breadboard components with TypeScript, with the added benefit of compile-time type checking.
Writing a Breadboard Type Expression simultaneously generates both a JSON Schema and a TypeScript type with matching semantics. The JSON Schema is automatically serialized and used by the Breadboard Runtime and Visual Editor, while the TypeScript type is used to enforce type safety when wiring components together with the Breadboard Build API.
Basic Types
The simplest Breadboard Type Expressions are the JSON primitive types, specified directly as strings:
"string"
"number"
"boolean"
"null"
Example
import { input } from "@breadboard-ai/build";
const numImages = input({
type: "number",
description: "How many images to generate",
});
String Formatting
To add formatting constraints to a string, use the string
function instead of
the "string"
literal.
Arguments
Pass an options object any of the following properties:
Example
import { string } from "@breadboard-ai/build";
const apiAddress = input({
type: string({ format: "uri", maxLength: 256 }),
});
Unknown
The "unknown"
Breadboard Type Expression matches any JSON value. In other
words it can be any of: string
, number
, boolean
, null
, object
, or
array
.
Example
import { input } from "@breadboard-ai/build";
const fetchResponse = input({
type: "unknown",
description: "The response for an HTTP request, could be anything".
});
Objects
Use the object
function to match a JSON Object.
Arguments
-
properties
(required): An object listing the properties the object has along with their types. Can be empty ({}
) to declare that the object has no properties. Properties are required by default, but can be wrapped inoptional
if needed (see Optional properties). -
additional
(optional): Allow the object to have additional properties (meaning not declared inproperties
) as long as they match the given type. (See Additional properties).
Note
The object
function declares a JSON Object, also known as a plain
object, which should not be confused with either JavaScript's Object
prototype nor with TypeScript's object
type, both of which are much broader
concepts. JSON Objects are strictly those objects which have been declared
with curly braces, and contain values that are themselves JSON-serializable.
Additional properties
If the second argument to object
is omitted, then the object will not allow
any additional properties, meaning only those properties listed in properties
are allowed.
To allow additional properties, pass a Breadboard Type Expression as the second
argument to object
. This can be "unknown"
to allow any JSON value, or
something more specific to constrain it further.
Optional properties
Properties passed to object
are required by default, but can be made optional
by wrapping the type with optional
.
Example
import { object, optional, input } from "@breadboard-ai/build";
const sensorReadingType = object({
sensorId: "string",
sensorDescription: optional("string"),
// e.g. {"2024-07-29": 37, "2024-07-30": 42}
sensorTimeSeries: object({}, "number"),
});
const sensorReading = input({
type: sensorReadingType,
description: "Time series data from a sensor",
});
Arrays
Use the array
function to match a JSON Array.
Arguments
itemType
(required): The type of the elements in the array. Any Breadboard Type Expression.
Example
import { array, object } from "@breadboard-ai/build";
array("string");
array("unknown");
array(
object({
timestamp: "string",
value: "number",
})
);
Composition
Use the anyOf
function to match at least one of the given types.
Generates a JSON Schema
anyOf
.
and a TypeScript
union
(|
).
Arguments
Specify 2 or more arguments, each any kind of Breadboard Type Expression.
Example
import { anyOf } from "@breadboard-ai/build";
anyOf("string", "number");
anyOf(
"string",
array("string"),
object({ value: "string" }),
array(object({ value: "string" }))
);
Enumerations
Use the enumeration
function to match a fixed set of values.
Generates a JSON Schema
enum
and a
TypeScript
union
(|
).
Arguments
Specify 1 or more fixed values. Each value can be a string, number, boolean, or null.
Example
import { enumeration, input } from "@breadboard-ai/build";
const fileType = input({
type: enumeration("video", "audio", "image", "text"),
});
// Mixed types are OK.
enumeration("foo", 123, true, null);
Forcing Schemas
Use the unsafeType
function to manually create a custom Breadboard Type
Expression with an exact given JSON Schema and TypeScript type.
This can be useful in cases where the JSON Schema and the TypeScript types are generated by an external process. It can also be useful if there is a feature of JSON Schema or TypeScript that would improve the type or schema, but which is not provided by the included utilities.
Note
This function is named "unsafe" because there is no guarantee that the JSON Schema and TypeScript types you specify are semantically equivalent. Prefer using one of the provided types if possible, and consider filing a feature request if you think a type should be natively supported.
Example
import { unsafeType } from "@breadboard-ai/build";
import type { ThingType } from "./my-type.js";
export const thing = unsafeType<ThingType>(
await import("./thing-schema.json", { with: { type: "json" } })
);
Breadboard Behaviors
Breadboard extends JSON Schema with a special field called behavior
. Use the
annotate
function to add a behavior
field to the underlying JSON Schema.
Example
import { annotate, input } from "@breadboard-ai/build";
const oldConfig = input({
type: annotate("string", {
behavior: ["config", "deprecated"],
}),
});