At a Glance
Owner: Sysadmin · Table:tb_dimension(+tb_dimension_display_in) · Used by: PR / PO / GRN / SR / IA / inventory / master records · User-extensible custom-field system — cost-centre, project code, GL override.
Dimensions are the user-extensible custom-field system. A dimension defines a named tag (cost_centre, project_code, gl_account_override, event_name, …) with a typed value space, default value, and a list of places it should appear — header of PR, detail of GRN, the vendor master, etc. End-user values are stored in the dimension JSONB column that every transactional table and most master records carry.
The two-table split keeps the catalogue clean. tb_dimension is the definition. tb_dimension_display_in is the display matrix — one row per place the dimension should appear (with per-place override defaults). This is how Carmen supports cost-centre tagging on PR headers and IA detail lines without hardcoded columns.
Maintained by Sysadmin. Read by every form that renders dimension fields, every cost-allocation report.
| Task | Where | Notes |
|---|---|---|
| Define a dimension | System Config → Dimensions → New | Set key, type, optional default value |
| Enable a dimension on a place | Dimension edit → display-in matrix | Checkbox grid against 24 enum values |
Curate lookup allowed values |
Dimension edit → value editor |
Required for lookup / lookup_dataset |
| Override default per place | Display-in row → default_value |
Wins over top-level dimension default |
| Retire a dimension | Set is_active = false |
Hides from new forms; existing values remain |
| Audit dimension changes | reporting-audit/activity log | entity_type = dimension |
| Symptom | Cause | Action |
|---|---|---|
| "Key already exists" | Duplicate among non-deleted | Pick different key or reactivate existing |
| "Value not in catalogue" | lookup value not in value JSON |
Add to catalogue or pick existing |
| Cannot hard-delete dimension | Documents have non-empty values for the key | Set is_active = false instead |
| Field missing from new form | display_in row missing or removed |
Add row in display-in matrix |
| Type mismatch on save | Document value violates type |
Form-side validation should reject earlier |
dimension JSON arrays store values at write-time; later catalogue edits do not retro-edit historical documents.default_value → top-level default_value → empty.Source: tenant schema.
tb_dimension| Field | Prisma Type | Nullable | Description |
|---|---|---|---|
id |
String @db.Uuid |
No | Primary key. |
key |
String @db.VarChar |
No | Programmatic key (e.g. cost_centre). Stored verbatim in document dimension arrays. |
type |
enum_dimension_type |
No | string, number, boolean, date, datetime, json, dataset, lookup, lookup_dataset. |
value |
Json? @db.JsonB |
Yes | Catalogue / allowed-values list. |
description / note |
String? |
Yes | Free text. |
default_value |
Json? @db.JsonB |
Yes | Top-level default. |
is_active |
Boolean? |
Yes | Default true. |
info |
Json? @db.JsonB |
Yes | Free-form metadata. |
doc_version |
Int |
No | Optimistic-concurrency token. |
| Audit columns | — | Yes | created_*, updated_*, deleted_*. |
Constraints: @@unique([key, deleted_at]). Index on [key].
tb_dimension_display_in| Field | Prisma Type | Nullable | Description |
|---|---|---|---|
id |
String @db.Uuid |
No | Primary key. |
dimension_id |
String @db.Uuid |
No | FK to tb_dimension.id. |
display_in |
enum_dimension_display_in |
No | Where the dimension shows up. |
default_value |
Json? @db.JsonB |
Yes | Per-place override. |
note / info / doc_version |
— | Mixed | Standard metadata. |
| Audit columns | — | Yes | created_*, updated_*, deleted_*. |
Constraints: @@unique([dimension_id, display_in, deleted_at]). Index on [dimension_id, display_in]. FK onDelete: NoAction.
enum_dimension_display_in: currency, exchange_rate, delivery_point, department, product_category, product_sub_category, product_item_group, product, location, vendor, pricelist, unit, purchase_request_header, purchase_request_detail, purchase_order_header, purchase_order_detail, goods_received_note_header, goods_received_note_detail, transfer_header, transfer_detail, stock_in_header, stock_in_detail, stock_out_header, stock_out_detail.
key unique among non-deleted; each (dimension_id, display_in) unique.type; lookup / lookup_dataset checked against value catalogue.../carmen-turborepo-backend-v2/packages/prisma-shared-schema-tenant/prisma/schema.prisma — tb_dimension (lines ~4608-4635), tb_dimension_display_in (lines ~4671-4692), enums (lines ~115-185).../carmen-turborepo-frontend/apps/web/app/(app)/configuration/dimension/.