Schema guide
Objects and schema.json: the file format, record ids, system fields and object-level options.
Everything starts with an object — a small schema.json that describes one table and how people
may use it. Objects live in objects/<name>/, and the folder name must match the object's name.
// objects/lead/schema.json
{
"name": "lead",
"labels": { "en": "Lead" },
"fields": [
{ "name": "id", "type": "string", "primary": true },
{ "name": "title", "type": "string", "required": true },
{ "name": "status", "type": "enum", "options": ["open", "won", "lost"], "default": "open" },
{ "name": "owner_id", "type": "string", "ownership": true }
],
"permissions": {
"sales": { "read": "own", "create": true, "update": ["title", "status"], "delete": true }
}
}weave migrate turns this into a PostgreSQL table plus REST/MCP surfaces. Your DDL never runs at
runtime — see Migrations.
In this section
- Fields & types — the type table, common attributes, enums,
seq_no - Relations —
relation/details/multiRelation - Validation — what the engine checks and where custom rules go
- Migrations — how
schema.jsonmaps onto an existing table - Named enums — declare a shared enum once in
enums/
Format version
The on-disk format is versioned, and new files carry a top-level schemaVersion:
{ "schemaVersion": 6, "name": "lead", "labels": { "en": "Lead" }, "fields": [ /* … */ ] }Files written before versioning existed are treated as legacy version 0. The engine migrates older
files in memory while loading, so they keep working; run weave schema:upgrade to stamp every file to
the current version (the change is auto-committed).
- v2 replaced the scalar
labelwith the per-localelabelsmap (writinglabelin a v2 file is rejected withobject.label.removed). - v3 added object-level
constraints(composite/scopedUNIQUE); additive, no rewrite. - v4 made
jsonmap to PostgreSQLjson(it previously mapped tojsonb);weave schema:upgraderewrites formerjsonfields tojsonb, andjsonis now free to mean PGjson. - v5 renamed the
personfield type touserand made the identity FK types (user,department) target the engine identity objects (weavekit_user/weavekit_department) implicitly — a declaredtargetand the legacyperson.departmentattr are dropped. - v6 added named enums: an enum may reference a declaration in
enums/<name>.jsonbyenumType(no inlineoptions). Additive — inline enums keep working.
A file declaring a version newer than the engine supports is rejected with
schema.version.unsupported — fail closed rather than misread a future format.
Record ids and system fields
A record's external id is its record_key — one URL-safe, decodable string that encodes the
ordered primary-key tuple (length-prefixed, so a value may contain any character):
encodeRecordKey(['O-1001']) === '6:O-1001'
encodeRecordKey(['O-1001', '3']) === '6:O-10011:3'REST uses it in /{id}, MCP in id, batch operations in ids[]. The engine returns it as the
read-only virtual field weave_id. Don't build it by hand — read it from a result (or request it
in fields) and pass it back.
The engine also keeps system metadata without touching your table (zero DDL): status, ownership,
actor and timestamps live in an engine-owned side table keyed by the record_key. They're exposed as
virtual fields — never returned by default, requested explicitly, always read-only:
| Virtual field | Meaning |
|---|---|
weave_id | the record's record_key (its external id) |
weave_status | instance status: draft / running / effective / canceled (default draft) |
weave_owner_id | owning subject (row-scope source) |
weave_created_by / weave_modified_by | actor ids |
weave_created_time / weave_modified_time | timestamptz |
weave_workflow_instance_id | bound workflow instance, or null |
describe_object (and GET /api/metadata?object=<name>) lists them with "virtual": true. Pass them
in fields to read them; they also work in filter / sort.
Object-level attributes
titleTemplate— composite title, e.g."{doc_no} {customer_name}".indexes— extra btree/gin/gist indexes:{ "type": "gin", "fields": ["tags"] }.constraints— declarative table-level UNIQUE constraints, e.g.{ "type": "unique", "fields": ["email", "tenant_id"] }. Use one for composite / scoped uniqueness (a per-fieldunique: truecovers a single column). Enforced by a realUNIQUE(...), so it's race-free; a violation returns409(data.unique). On an existing table it's added viaADD CONSTRAINTunderalter: true.permissions— see RBAC.labels/description— display and introspection metadata.