Named enums
Declare a shared enum once in enums/ and reference it by enumType across objects.
A named enum is a project-level enum declaration shared by any number of objects. Instead of
repeating the same options list in every schema.json, you declare it once under enums/ and
reference it from each field by enumType:
enums/invoice_status.json → the declaration (the source of truth)
objects/invoice/schema.json → { "name": "status", "type": "enum", "enumType": "invoice_status" }
objects/payment/schema.json → { "name": "state", "type": "enum", "enumType": "invoice_status" }Every field that shares an enumType shares one native PostgreSQL enum type — the values are
declared once, and adding a value is a single-file edit.
Declaring an enum
One file per enum in enums/; the file name must equal the enum name, which must be a
snake_case identifier (it is also the PostgreSQL type name):
// enums/invoice_status.json
{
"name": "invoice_status",
"values": ["open", "paid", "void"],
"labels": {
"en": { "open": "Open", "paid": "Paid", "void": "Void" },
"fr": { "open": "Ouverte", "paid": "Payée", "void": "Annulée" }
}
}values— the allowed values (non-empty, unique). These are the stored values.labels— optional per-value display names, keyed by locale then value (optionLabelsindescribe_object). A label key must be one ofvalues.
The declaration directory is <schemaDir>/enums/. It is optional: a project with no enums/ behaves
exactly as before.
Referencing an enum
A field references a declared enum by its enumType and omits options:
{ "name": "status", "type": "enum", "enumType": "invoice_status", "default": "open" }multiple: true produces enumType[] (still the one shared type). At load the reference is
resolved to the declared values, so describe_object, generated TypeScript, OpenAPI and the MCP
tool surface all see the same option set.
The four enum field forms
| Form | schema.json | Storage |
|---|---|---|
| Inline (static) | { "type": "enum", "options": ["open", "paid"] } | native PG enum <object>_<field> |
| Inline + explicit name | { "type": "enum", "options": ["open", "paid"], "enumType": "custom_status" } | native PG enum custom_status |
| Named reference | { "type": "enum", "enumType": "invoice_status" } | native PG enum invoice_status (shared) |
| Data-driven | { "type": "enum", "options": { "from": { "object": "currency" } } } | VARCHAR / TEXT[] |
The first three are static (a native PG enum); the fourth is a dynamic set read from another
object's column at write time — see enum.options.
enumType has a dual role: when it matches a declaration in enums/ it is a named reference;
otherwise it is an explicit native type name.
Storage and migrations
weave migraterunsCREATE TYPE <enum>once for a shared enum (not once per field), andALTER TYPE <enum> ADD VALUE IF NOT EXISTSfor new values on managed objects. DDL stays additive-only: values are never removed or renamed (PostgreSQL forbids it).- Adding a value: edit
enums/<name>.json, runweave migrate. Removing a value is not supported — to retire a value, keep it declared but stop using it. - Adopted (read-only) tables are never altered; a named enum that mirrors an existing type is informational.
Validation and CLI
Loading fails closed:
enum.invalid— the declaration is malformed (name / values / labels).enum.unknown— a fieldenumTypereferences a declaration that does not exist.enum.options.mismatch— inlineoptionsare given alongside a declaredenumTypebut disagree with it (or a named enum is combined with a data-drivenfrom).
Use weave enum:check in CI: it validates every declaration and every objects/<name>/schema.json
reference without a database. weave enum:list prints the declared enums; weave field:add --enum <name>
adds a named-reference field.
weave enum:list
weave enum:check
weave field:add invoice --name status --type enum --enum invoice_statusComputed fields and multiple
defaultmust be a subset of the declared values.multiple: trueis a multi-select (enumType[],TEXT[]-equivalent storage);multiplecannot beprimaryorunique(same rule as inline enums).
Related
- Fields & types — the full type table and
enum.options - Schema guide — format version and system fields
- Modeling: shared enum vocabularies — a worked practice
- CLI reference —
weave enum:list/enum:check