Schema
JSON documents
A jsonb column can be declared two ways. col.jsonb().$type<T>() types the document
for TypeScript and tells the server nothing about it. col.jsonb(shape) takes a
shape built with json.*, which types the document the same way and also
describes it to the server.
import { defineTable, col, json } from "@rebasepro/server/schema";
export const pages = defineTable("pages", { columns: { id: col.uuid().primaryKey().defaultRandom(),
// Typed for TypeScript only. settings: col.jsonb().$type<{ theme?: "light" | "dark"; pinned?: boolean }>(),
// Typed, and known to the server. seo: col.jsonb(json.object({ title: json.string().validate({ max: 60 }).required(), canonicalUrl: json.string().validate({ url: true }), noIndex: json.boolean().default(false), })), }, rls: "admin-only",});With a shape, the server:
- validates each field before a write, with the same rules a column takes;
- applies defaults to fields that are absent on create;
- stamps date fields with
.onCreateNow()/.onUpdateNow(), and user fields with.onCreateUser()/.onUpdateUser(), at any depth; - runs each field’s
.transform()hooks; - finds the files a document references (
json.storage()), so the orphan sweep counts them; - can search inside the document: a
searchfield may name a path such as"seo.title"(see Search).
The shape is served with the table’s descriptor, so the CMS can build a form for
the document without being told how. col.jsonb().$type<T>() gets a generic JSON editor
instead.
Builders
Section titled “Builders”| Builder | Holds | TypeScript type |
|---|---|---|
json.string() |
a string | string |
json.number() |
a number | number |
json.boolean() |
a boolean | boolean |
json.date() |
an instant, as an ISO string | string |
json.geopoint() |
a point on Earth | { latitude: number; longitude: number } |
json.storage(options) |
the path of a stored file | string |
json.object(fields, { additional? }) |
an object with known keys | an object type: required fields required, the rest optional |
json.array(of) |
an array of one shape | an array of of’s type |
json.oneOf(variants, { typeField?, valueField? }) |
a typed block | a union of { type: "<variant>"; value: <its type> } |
json.unknown() |
anything | unknown |
json.storage() takes the same options as col.storage().
json.object(fields, { additional: true }) also accepts keys it does not name.
Modifiers
Section titled “Modifiers”| Modifier | On | What it does |
|---|---|---|
.required() |
every field | The key must be present in the document. Makes the key non-optional in the type. |
.default(value) |
every field | The value written when the key is absent on create. |
.describe(text) |
every field | What the value is, for OpenAPI and MCP. |
.validate(rules) |
every field | The rules a column of the same kind takes: text rules on json.string(), numeric rules on json.number(), date bounds on json.date(), item counts, uniqueItems and uniqueBy on json.array(). See Validation. |
.transform({ beforeSave?, afterRead? }) |
every field | Field-level hooks, run on the server. value is T | undefined unless .required() comes first. |
.oneOf(values) |
json.string(), json.number() |
A closed set of accepted values, typed as their union. |
.onCreateNow() |
json.date() |
The server writes the current time when the row is created. |
.onUpdateNow() |
json.date() |
The server writes the current time on every write. |
.onCreateUser() |
json.string() |
The server writes the acting user’s id when the row is created, or null when nobody is acting. |
.onUpdateUser() |
json.string() |
The server writes the acting user’s id on every write. |
.userId() |
json.string() |
The value is a user’s id: the panel offers a user picker, and a caller who may write the table may look users up to fill it. See User columns. |
Fields are optional unless .required(). A required key is required in the
TypeScript type too:
import { col, json } from "@rebasepro/server/schema";
const address = json.object({ street: json.string().required(), city: json.string().required(), country: json.string().validate({ length: 2, uppercase: true }).required(), notes: json.string(),});
// { street: string; city: string; country: string; notes?: string }const shipping = col.jsonb(address);Stamps inside a document
Section titled “Stamps inside a document”Stamps work at any depth of a JSON column: object fields, each array item, and
the value of a oneOf item whose type names the variant. On a create,
missing objects on the way to a stamp are created. On an update, only the
onUpdate* fields are stamped, and only inside a document the update sends; a
document it does not send keeps its stored value. A stamp replaces whatever the
write sent, and a field’s .default() fills it first.
Arrays and typed blocks
Section titled “Arrays and typed blocks”json.array(of) is a list of one shape. json.oneOf(variants) is a block whose
type key says which variant it is and whose value key holds that variant’s
content. As the items of an array, it is the shape of a block editor:
import { defineTable, col, json } from "@rebasepro/server/schema";
export const articles = defineTable("articles", { columns: { id: col.uuid().primaryKey().defaultRandom(), body: col.jsonb(json.array(json.oneOf({ paragraph: json.string(), image: json.storage({ path: "articles/images/", accept: ["image/*"] }), quote: json.object({ text: json.string().required(), author: json.string() }), }))), }, rls: "admin-only",});A row’s body is then typed as an array of:
type Block = | { type: "paragraph"; value: string } | { type: "image"; value: string } | { type: "quote"; value: { text: string; author?: string } };json.array(json.object({...})).validate({ uniqueBy: ["sku"] }) refuses two
items that share a value in a named field (unique_by; absent and null
values are not compared, and a $push checks the pushed items among
themselves). validate({ uniqueItems: true }) refuses two equal items.
The top of a document may itself be a scalar or a json.oneOf, and
json.unknown() is a field of any JSON value; the server checks each shape on
REST, MCP and socket writes.
typeField and valueField rename the two keys, for documents that already use
other names: json.oneOf({ … }, { typeField: "kind", valueField: "data" }).
jsonb or json
Section titled “jsonb or json”col.json() takes the same arguments as col.jsonb(). It stores the text it was
given, key order and whitespace included, and cannot be indexed or searched the
way jsonb can. Use it only when the exact text matters; otherwise use
col.jsonb().
A point on Earth has its own column builder, col.geopoint(), stored as jsonb.
A list of plain values that Postgres should index is often better as an array
column: col.text().array(). Nested lists belong in jsonb: .array() of
an array is refused.
Next steps
Section titled “Next steps”- Columns: the column builders and their validation rules
- Search: searching paths inside a document
- Table hooks:
.transform()and the table-level hooks