Domain tables

A domain table is an ordinary table used as a lookup. When an attribute points at a domain table, the records in that table become the only valid values for the attribute.

This is how you get referential integrity without writing a single validation rule.

There is no separate object type

Any table with the Use this as a reference table switch on (API name: code_generation = MANUAL) can act as a domain table. The same table can hold real business data and be referenced from elsewhere.

Why a reference table is required

A lookup is only useful if the person choosing a value can recognise what they are choosing. The picker shows the target record’s identifier and display name (named Code and Name by default):

SEK - Swedish krona
EUR - Euro
USD - US dollar

On a standard table, the identifier is machine-generated and means nothing to a person. So only reference tables appear in the domain table selector.

A worked example

Create a Currency table, turn on Use this as a reference table, and add no extra attributes at all:

Code	Name
SEK	Swedish krona
EUR	Euro
USD	US dollar
GBP	Pound sterling

Now, on your Accounts table, create an attribute called currency and point it at Currency. Users filling in an account get a searchable picker instead of a free-text box, and a misspelled SEK with a trailing space becomes impossible.

Domain tables can carry extra data

Currency above is minimal, but a domain table is a normal table. A Counterparty domain table might carry lei_code, country and rating attributes as well — and those can themselves be domain attributes pointing at other lookups.

Parent-child hierarchies

A domain table can reference itself. For example, an OrgUnit table can have an optional parent attribute that also points to OrgUnit. Each row can then point to another row in the same table to represent its parent. This is a regular domain reference; it does not automatically enforce tree rules such as preventing cycles.

What is actually stored

When a user picks SEK - Swedish krona, Grunddata stores the source_id of that currency record — not the text.

This has two consequences worth understanding:

Renames propagate instantly

Correct a typo in the Currency table and every record referencing it shows the corrected label immediately. There is nothing to re-key and nothing to re-import.

Referenced records should not be deleted casually

Deleting a record that other records point at leaves those references pointing at something that is no longer active. Before removing a lookup value, check whether it is in use.

Setting it up

1. Create the lookup table and turn on Use this as a reference table.

2. Add its records. The identifier and display name columns are mandatory; add attributes only if the lookup carries extra information.

3. On the referencing table, create an attribute and choose the domain table model and the domain table. The datatype becomes read-only.

4. Save. The attribute now renders as a searchable picker.

Set the domain table before loading records

A domain table cannot be set on an attribute in a table that already holds records — existing free-text values could not be resolved to target records. If you already have data, create a new attribute, migrate the values, and remove the old one.

Cascading domain attributes

When a lookup is large, filter it by another selection on the same row. Tick Cascade domain values from another domain attribute on the child attribute and choose the cascade parent attribute.

country  = Sweden
   ↓ filters
region   = only Swedish regions offered
   ↓ filters
branch   = only branches in the chosen region

Both the parent and the child must be domain attributes on the same table.

Order the attributes to match the cascade

Put the parent attribute before the child in the attribute order. Users then fill the fields in the order the cascade expects, which is far less confusing — especially in a spreadsheet, where columns are read left to right.

Domain values in views and OData

A domain attribute is not exposed as a single field over OData. Instead a view can publish up to three separate fields for it:

View field	Contains
{Attribute}SourceId	The referenced record’s source_id
{Attribute}Code	The referenced record’s Code
{Attribute}Name	The referenced record’s Name

For example, a Counterparty domain attribute becomes CounterpartySourceId, CounterpartyCode and CounterpartyName.

Tip

Publish all three. Reports use Code and Name; integrations join on SourceId. They cost nothing extra.

Common domain tables to create first

Table	Typical codes
Currency	SEK, EUR, USD
Country	ISO 3166 codes
Counterparty	LEI codes or internal counterparty codes
CostCentre	Internal cost centre codes
AccountType	NOM, MTM, INT

Tip

Keep shared lookups together in a single Reference model. An attribute may reference a domain table in any model, so there is no reason to duplicate Currency per domain.