Your data
Schemas
A schema describes what a document must look like; bind it to a collection and the service refuses every write that does not match.
A schema says what a document must look like: which fields, of which type, which are required, which values are allowed. Bind one to a collection and every POST, PUT and PATCH is checked on the server before it is stored, whoever sends it.
Use it to keep your data clean. For example, a product schema can require a name and a price that is a number and not negative.
What you get:
-
Clean data from every client. The check runs on the server, so it covers your app, scripts and AI agents alike.
-
Clean data even when a form misses a check. Your app can check its forms to show a clear error early, and the service checks every write again.
Schemas are JSON Schema draft-07, stored in the schemas collection and managed under Schemas.
Write a schema
Click Create schema, choose an _id and paste the schema. This one validates a product:
{
"_id": "product",
"title": "Product",
"description": "A product of the catalog",
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"name": { "type": "string", "minLength": 1 },
"price": { "type": "number", "minimum": 0 },
"category": { "type": "string", "enum": ["electronics", "clothing", "food"] },
"inStock": { "type": "boolean" }
},
"required": ["name", "price", "category"]
}
The _id is how you will refer to it. title and description show in the list. The rest is JSON Schema; these are the keywords you will use most:
| Keyword | What it does |
|---|---|
|
|
|
The fields, and which of them must be present. |
|
The only values allowed. |
|
Ranges, lengths, and a regular expression for strings. |
|
The schema of each element of an array. |
|
Refuse fields that are not in |
|
A rule that depends on another field. |
{"$ref": "bson#/date"}. Or declare a date field inline as {"type": "object", "properties": {"$date": {"type": "number"}}}: inside a schema $date is written $date, and a document sends the date as {"$date": <epoch millis>}, which is also what a permission’s @now stores.
The editor checks the JSON as you type. The full vocabulary is in the JSON Schema draft-07 specification.
Bind it to a collection
A schema does nothing until a collection uses it. On the Collections page, click the gear of the collection, choose the schema under Schema, and click Save.
One schema can serve several collections. Editing it affects all of them, for writes from then on: documents already stored are not checked again.
What your app sees
A document that does not match is refused with 400 Bad Request and a body that says why:
{
"http status code": 400,
"message": "Document validation failed",
"exception": { "message": "required key [customerId] not found" }
}
Show that message to the user, or map it to your form. A PATCH is validated on the document as it would be after the change, so a partial update cannot leave a document invalid.
From a script
| Operation | API |
|---|---|
List |
|
Create |
|
Update |
|
Delete |
|
Bind to a collection |
|
Deleting a schema does not unbind it: a collection that still references it refuses every write until you bind another or remove the reference.
Do it from the command line
You can keep your schemas in git and apply them with ulabase setup. The steps below save the product schema and make products validate every write against it:
import { defineSetup, step } from '@ulabase/cli';
// the JSON schema every product must match
const product = {
$schema: 'http://json-schema.org/draft-07/schema#',
title: 'Product',
type: 'object',
properties: {
name: { type: 'string', minLength: 1 },
price: { type: 'number', minimum: 0 },
},
required: ['name', 'price'],
};
export default defineSetup('Catalog', [
// step 1: save the schema once; after editing it, run with --force to save it again
step('product schema stored', {
check: ({ service }) => service.schemaExists('product'),
apply: ({ service }) => service.putSchema('product', product),
}),
// step 2: make the products collection check every write against the schema
step('products validated by product', {
async check({ service }) {
const meta = await (await service.fetch('/products/_meta')).json();
return meta.jsonSchema?.schemaId === 'product';
},
apply: ({ service }) =>
service.fetch('/products', {
method: 'PATCH',
body: JSON.stringify({ jsonSchema: { schemaId: 'product' } }),
}),
}),
]);
The first check asks only whether the schema exists. After you edit the schema, send it again with --force 'product schema' (see Forcing a step).
A schema you read back is not exactly the one you wrote: the service adds $id and id, and turns _$date into $date. A check that compares the content must leave those out.
Related pages
-
Constraints: rules across documents, which a schema cannot express.
-
Indexes: a unique index, for a field that must not repeat.
-
Collections and documents: where the schema is bound.