Lookups and Reference Data
Reference data provides the controlled vocabularies, enumerations, and master records that domain modules use for dropdown lists, validation, and display formatting. Foundation centralises this data so that every module draws from a single source of truth.
Lookups
A lookup is a named enumeration — a category of allowed values. Each lookup has a type code that other areas of the platform reference.
Key attributes:
| Attribute | Purpose |
|---|---|
| Type | Unique code within the tenant |
| Name | Human-readable name with i18n support |
| Customisation level | Controls whether tenants can modify the values |
Lookup values
Individual values within a lookup. Each value belongs to exactly one lookup type:
| Attribute | Purpose |
|---|---|
| Code | Machine-readable code (e.g. FILE, URL, SHORT_TEXT) |
| Meaning | Display text with i18n support |
| Display sequence | Sort order within the lookup |
| Enabled flag | Whether the value is selectable (without deleting it) |
| Tag | Optional grouping tag for filtering subsets |
Validation
Lookups are validated when data is saved — the platform ensures that any referenced lookup value exists and is active. This allows lookups to be disabled without breaking existing references.
Key-value pairs
A simpler alternative to lookups for arbitrary configuration data. Key-value pairs store tenant-scoped settings that do not need the structured enumeration model:
| Attribute | Purpose |
|---|---|
| Key | Unique key within the tenant |
| Value | The stored value |
| Description | What the setting controls |
Countries
Master list of countries with standardised codes and geographic metadata:
| Attribute | Purpose |
|---|---|
| Country code | ISO 3166-1 alpha-2 code (e.g. NZ, AU, US) |
| Alpha-3 code | ISO 3166-1 alpha-3 code (e.g. NZL, AUS, USA) |
| Name | Display name with i18n support |
| Nationality | Demonym (e.g. New Zealander, Australian) |
| Region/sub-region | Geographic classification |
| Phone code | International dialling prefix |
Currencies
Master list of currencies with formatting and rounding rules:
| Attribute | Purpose |
|---|---|
| Currency code | ISO 4217 code (e.g. NZD, AUD, USD) |
| Name | Display name with i18n support |
| Precision | Decimal places for arithmetic |
| Minimum accountable unit | Smallest unit (e.g. 0.01 for cents) |
| Rounding rule | How to round amounts |
| Symbol | Display symbol (e.g. $, €, £) |
Units of measure
Standard units for quantities across the platform:
| Attribute | Purpose |
|---|---|
| Code | Unique code (e.g. KG, LB, EA) |
| Name | Display name with i18n support |
| Class | Category (e.g. WEIGHT, LENGTH, QUANTITY) |
| Base unit | Base unit for conversion within the class |
| Conversion rate | Multiplier to convert to base unit |
How other modules use reference data
Other modules reference lookup values by storing the lookup code (e.g. as a category or status code). The platform validates these references when data is saved, ensuring consistency.
Countries and currencies are referenced by their ISO codes. Units of measure are referenced by their unit code. All reference data is tenant-scoped.