Shared enum vocabularies
Keep one status vocabulary across objects with a named enum.
A closed set that more than one object must agree on — a ticket's lifecycle status, a payment state, a risk grade — is a vocabulary. If each object carries its own copy of the option list, the lists drift ("pending" on one object, "waiting" on another) and only the database notices at write time.
A named enum declares the vocabulary once and lets every object reference it. The engine then backs all of them with a single native PostgreSQL enum type.
The scenario
A support product has two objects that both carry the ticket lifecycle:
tickets— the currentstatus;ticket_events— an append-only log whoseto_statusrecords the status a transition moved into.
Both must accept exactly the same values, and both should show the same localized labels.
1. Declare the vocabulary once
// enums/ticket_status.json
{
"name": "ticket_status",
"values": ["open", "pending", "resolved", "closed"],
"labels": {
"en": { "open": "Open", "pending": "Pending", "resolved": "Resolved", "closed": "Closed" },
"fr": { "open": "Ouvert", "pending": "En attente", "resolved": "Résolu", "closed": "Fermé" }
}
}The file name equals the enum name equals the PostgreSQL type name (ticket_status).
2. Reference it from both objects
// objects/tickets/schema.json
{ "name": "status", "type": "enum", "enumType": "ticket_status", "default": "open" }
// objects/ticket_events/schema.json
{ "name": "to_status", "type": "enum", "enumType": "ticket_status", "required": true }Neither field declares options — the values come from the declaration. weave migrate creates the
ticket_status type once and both columns use it.
3. What stays consistent for free
Because the values live in one place, every surface reads the same set:
- REST metadata —
GET /api/metadata?object=tickets(andticket_events) returns the sameoptionsplus the per-valueoptionLabels, so a front-end renders one vocabulary. - MCP —
describe_objectshows an agent the same options for both objects, so it cannot invent a status the database rejects. - OpenAPI —
weave openapiemits onecomponents.schemas.ticket_statusthat both object schemas$ref, instead of two duplicated inline enums. - TypeScript —
weave typesemits oneTicketStatusunion used by both interfaces.
4. Evolving the vocabulary
Adding a status is a single edit:
"values": ["open", "pending", "resolved", "closed", "escalated"]Run weave migrate; the engine issues ALTER TYPE ticket_status ADD VALUE IF NOT EXISTS 'escalated'
on managed tables, and both objects immediately accept it. Removing or renaming a value is not
supported (PostgreSQL cannot drop an enum label) — retire a value by leaving it declared and simply
not using it.
Guardrails
- Run
weave enum:checkin CI: it validates everyenums/<name>.jsonand everyenumTypereference inobjects/without a database, so a typo (ticket_stat) fails the build instead of at write time. - Adopted (read-only) tables are never altered — a named enum that mirrors an existing type is informational only.
- Keep the vocabulary small and stable. A set that is actually data (currencies, categories stored
in a table) is a dynamic
enum.options.from, not a named enum.
When to reach for it
| Situation | Use |
|---|---|
| One object, one closed set | inline options — no need to declare |
| Several objects share a closed set | named enum (this page) |
| Values come from another table's rows | enum.options.from |
| A record reference (navigate/expand) | relation |
Related
- Named enums (reference)
- CLI reference —
weave enum:list/enum:check - RBAC — permissions are declared per object, independent of the vocabulary