Dictionary

Deep reference

This page documents the dictionary metadata layer — labels, formats, BOOLEAN / ENUM / LOOKUP rules and form-layer defaults (LOGIN, SYSDATE, SEQUENCE, PASSWORD). For task-oriented use — configure columns on a screen, scaffold a sequence or a lookup — see Build → Screens → Columns and Build → Queries → Sequences and lookups.

The dictionary is the shared metadata layer that turns a raw column name into a readable interface. A connector query returns columns the database knows by their identifier (customer_status, due_date, invoice_amount); the dictionary attaches:

• A localised label ("Statut client", "Date d'échéance", "Montant facture").
• A display rule (BOOLEAN toggle, ENUM chip, LOOKUP against another connector).
• A number / date format ("€ 1 234,56", "dd/MM/yyyy").
• Form-layer defaults for write screens (auto-fill with the current user, the current date, a generated sequence, a hashed password).

Defined once in Settings → Dictionary, referenced by every screen, chart and dashboard that consumes the corresponding column. Change the label here and every consumer reflects it on the next render.

---

At a glance

---

Settings → Dictionary

The page has two tabs: Columns (one entry per logical column) and Lookups (named value sets that columns reference).

Columns tab

Settings → Dictionary · Columns

Search column…+ New column

Name

Label (en)

Type

Rule

Format

customer_status

Customer status

string

LOOKUP

—

✏️

due_date

Due date

date

—

dd/MM/yyyy

✏️

invoice_amount

Invoice amount

decimal

—

1 234,56 €

✏️

is_active

Active

bool

BOOLEAN

—

✏️

Click + New column or any row to open the column editor.

---

The column editor

Field	Effect
Name	The dictionary key — short, snake_case (customer_status). Connector column hints reference this name to pick up the metadata.
Label	A per-language map of display labels. The editor shows one input per loaded language. Falls back to the Name when a language is missing.
Description	Optional. Surfaces as the tooltip on form inputs and column headers.
Type	string / int / float / decimal / bool / date / datetime / time. Drives the default widget on screens (text input vs date picker vs checkbox).
Format	For numbers and dates — a format string (1 234,56 €, dd/MM/yyyy). The grid cell and the form input render with this format.
Rule	— (no special rendering) / BOOLEAN / ENUM / LOOKUP / PASSWORD. See Display rules.
Lookup	Visible only when Rule is LOOKUP. Dropdown of lookups defined on the Lookups tab.
Enum values	Visible only when Rule is ENUM. A sortable list of { value, label(s), colour } rows.
Form-layer defaults	Optional. See Form-layer defaults.
Required	Marks the field as required by default on every form. Per-screen overrides can still relax this.
Read-only	Marks the field as read-only by default on every form.

A Save rebuilds the dictionary registry; consumers (screens, charts) re-render with the new metadata on their next refresh.

---

Display rules

The Rule field changes how a column is rendered in a grid cell, in a form input and in a filter chip.

BOOLEAN

A bool column renders as a chip / toggle. The form input is a switch. The filter is a tri-state pill (All / Yes / No).

The editor exposes:

Field	Effect
True label	Defaults to "Yes" — per-language map.
False label	Defaults to "No".
True colour / False colour	Pill backgrounds in the grid.

ENUM

A small, static set of values declared on the column itself. Use when the values are known at design time and never change at runtime (e.g. low / medium / high).

Field per value	Effect
Value	The literal stored in the database.
Label	Per-language display label.
Colour	Pill background.
Order	Drag handle to re-order.

Renders as a coloured chip in grids, a dropdown on forms, a multi-select in filters.

LOOKUP

A dynamic set of values pulled from another connector query. Use when the values live in a table and may grow over time (statuses managed by an operator, country lists, etc.).

The column points at a Lookup entry; the lookup itself is defined on the Lookups tab — see below.

PASSWORD

Masks the value in grids (••••••••) and renders a password input on forms. Combined with the Form-layer default PASSWORD, sets up an Argon2-hashed write path that's safe by construction.

---

Lookups tab

A lookup is a named query that returns { value, label } rows. Columns set Rule = LOOKUP + point at a lookup to render their values as labelled chips.

Settings → Dictionary · Lookups

+ New lookup

Name

customer-statuses

Connector

billing ▾

Query

statuses-list ▾

Value column

code ▾

Label column

label ▾

Colour column

colour ▾

Cache

Per session ▾

Field	Effect
Name	Identifier referenced by column entries (customer-statuses).
Connector / Query	The SQL connector and named read query that returns the values.
Value column	Column in the query result that holds the stored value (what the database carries on each row).
Label column	Column in the query result that holds the display label. Localised through the dictionary when the query joins a translations table.
Colour column	Optional. Drives the chip background colour in grids.
Filter from	Optional dependencies — see cascading filters.
Cache	None / Per session / Per request. Drives how aggressively the framework caches the lookup. Default Per session.

A Test button at the top runs the underlying query and shows the resolved { value, label } pairs — useful to confirm the columns line up.

---

Form-layer defaults

The Form-layer defaults field of the column editor lets a column auto-populate on insert / update without the user typing the value. Four special tokens are recognised:

Token	Effect at save time
SEQUENCE	Pulls the next value of a database sequence — useful for generated identifiers when the database doesn't auto-increment.
SYSDATE	Sets the value to the server's current timestamp.
LOGIN	Sets the value to the calling user's identifier (the JWT's sub).
PASSWORD	Hashes the field's plain value with Argon2 before storing. Combined with Rule = PASSWORD it produces a safe-by-construction write path.

Form-layer defaults run on the server at save time — the client never sees them. An audit column auto-populated with LOGIN cannot be tampered with from the browser.

---

Display rules vs form-layer rules

The two concepts are easy to confuse. The table:

Aspect	Display rule	Form-layer rule
Where it runs	On the client (renderer).	On the server (save handler).
What it changes	How the value looks.	What the value is.
Examples	BOOLEAN → chip; ENUM → coloured pill; LOOKUP → labelled chip from a table.	LOGIN → caller's username; SYSDATE → now(); PASSWORD → Argon2 hash.
Visible to the user?	Yes.	No — the value is computed at save.

Both can apply to the same column. A typical Created by audit column has Rule = LOOKUP (against a users table, to show the display name) and Form-layer default = LOGIN (so the value is set automatically on insert).

---

Localisation

Every text field in the column editor — Label, Description, True label / False label, Enum label — is a per-language map. The editor shows one input per loaded language; missing languages fall back to the resolution chain documented under i18n.

Operators add languages from Settings → Languages; new languages then appear as extra columns in the dictionary editor.

---

Permissions

The Dictionary tab is gated by settings:dictionary. Lookups inherit the permission of their underlying SQL query — a caller who can't run sql:billing:statuses-list doesn't see the lookup values; the dropdown renders empty.

---

Tips & best practices

• Define a dictionary entry per logical column, not per database column. If customer_status and supplier_status share the same lookup, one dictionary entry covers both — point both connector hints at it.
• Keep labels short. Long labels truncate in grid headers. The Description field is the right home for explanations.
• Use ENUM when the values are known at design time, LOOKUP when they aren't. A priority enum (low / medium / high) is fine inline; a country list belongs in a lookup.
• Cache lookups Per session. Per-request caching adds a query on every screen open; None is rarely needed.
• Audit columns: LOOKUP + LOGIN / SYSDATE. The cleanest pattern — readable on display, auto-populated on save.

---

Under the hood

Dictionary definitions are stored in liberty-apps/config/dictionary.toml. Operators do not edit this file by hand in normal operation; the Dictionary builder is the canonical interface. The Raw TOML tab of Settings → Dictionary is the escape hatch when a builder gap blocks an advanced edit.

---

What's next

• Connectors — where column hints bind a discovered SQL column to a dictionary entry.
• Screens — how column metadata shapes the grid + edit dialog.
• Form conditions — conditional visibility / required / disabled rules on top of dictionary rules.
• Apps & Plugins → i18n — adding languages.