Lookup Tables
Operator-curated reference tables managed inside the ODD Platform — schema, data, RBAC, and API surface.
Lookup Tables are operator-curated reference tables that live inside the ODD Platform itself rather than in an external source system. The platform manages their lifecycle end-to-end: schema definition, row-level data entry, versioning of structure changes, RBAC, and read access via the platform's API. Each lookup table is exposed in the catalog as a standard Data Entity (entity type LOOKUP_TABLE, ID 24), so existing search, tagging, descriptions, and term-linking flows apply uniformly.
In the platform UI, lookup tables live under the top-level Master Data tab → Lookup Tables. The same page name appears throughout the API and code as "Lookup Table"; "Master Data" is the toolbar tab label, "Lookup Table" is the per-row noun.

Creating a Lookup Table
The creation of Lookup Tables involves adding a new table through the +Add new button in the right upper corner of the Master Data section. On a physical level, this implies that an actual table will be generated by ODD using the specified configuration connection. These tables are entirely managed by the ODD Platform.

When a Lookup Table is created a Data Entity of type "lookup table" is generated.

The Table name entered during creation is assigned to it as a Business Name. Simultaneously, an Original Name is provided, prefixed with the ID of Namespace. This prefix is added to distinguish tables with potentially identical names and it ensures that the tables adhere to a format acceptable for PostgreSQL.

The Original Name of Lookup Table functions as a table identifier within PostgreSQL, allowing it to be identified by the users. This information is useful when tasks such as uploading the table elsewhere or establishing a direct connection to the table data are required.
Lookup Table structure
The creation of the Lookup Table structure starts with column creation on a Structure Tab. Column creation starts with +Add column button and requires the specification of Column Name.

In contrast to the Table Name, which can assume any format, the right selection of name at this stage is crucial and adhering to a specific format is considered essential.

Further, the creation of Descriptions occurs at this point. Essentially, the columns that will be generated within the current table are the focus of these descriptions. The final step in creating a column involves selecting a Data Type. Currently, a limited list of PostgreSQL data types is supported for columns (see Supported field types below). Once the Column Name, Description and Data Type are provided, the column is created by clicking on the Add column button.

It is possible to further edit, i.e. to rename column or edit the description for that column, or delete columns:

Once a column is created and its corresponding data type is already selected, the alteration of that data type becomes impossible.

If there is a need to change the data type for a column, a secure approach involves the:
creation of a new column with the desired data type,
transfer of the old column data to the new column, and
deletion of the old column.
This method ensures a secure approach to any data migration.
Each time the table structure is modified, a new revision of structure is generated, allowing table version differences to be tracked.

Supported field types
A column's data type is selected once at column creation and cannot be changed afterwards (use the migration pattern above). The platform exposes the following PostgreSQL types via the LookupTableFieldType enum:
VARCHAR
varchar
Variable-length text.
INTEGER
integer
4-byte signed integer.
SERIAL
serial
Auto-incrementing integer (typical for synthetic keys); the primary-key id column is generated automatically and cannot be redefined.
DECIMAL
numeric
Arbitrary-precision decimal.
BOOLEAN
boolean
True/false.
DATE
date
Calendar date (no time component).
TIME
time
Time of day (no date component).
JSON
json
JSON document.
UUID
uuid
128-bit identifier.
Per-column validation is also configurable: each field carries is_nullable (default true), is_unique (default false), and an optional default_value string.
Adding and managing data
Within ODD Platform an exclusive Data tab is made available for Lookup Tables. It displays a table with headers that mirror the structure of Lookup Table, which is created in the Structure tab. When a column is added in the Structure tab, its appearance in the Data tab is immediate.
Data values can be inputted into the table columns by clicking on [+] button within the Data tab.

This table has a flexible structure, allowing addition of multiple diverse columns.

Even after filling in the columns with data, the table structure remains customizable, i.e. it is still possible to edit, add or delete its columns. The filled in data is also subject to be edited or deleted.

The information entered into the table resides in a separate schema within the database (lookup_tables_schema — see Direct database access below).
Lookup Table vs regular Data Entity
The Lookup Table is essentially the same as regular Data Entity in ODD. The key difference lies in the fact that for a standard data entity there is no direct ability to modify its structure while for a lookup table the interaction with the structure becomes possible.
All the actions possible with the structure in any other data entity, such as adding Descriptions, Tags, Terms and Business Names can be performed both with Lookup Table itself and its columns also.

Also, the ID column, marked as the Primary Key, is automatically generated and cannot be modified. While the Primary key is currently unchangeable, there are plans for future developments that will enhance user experience by allowing interaction with it.
Accessing Lookup Table data
Access to the data in the Lookup table is available by the distinct schema within PostgreSQL, and it can also be accessed via an API.
Access via an API is currently considered not the most user friendly or recommended method, because with this access for example only column IDs are accessible and not their corresponding names. Nevertheless, assistance from our team is available to users in configuring access, ensuring that additional data can also be made available through the API in such cases. The full surface is documented at API Reference → Reference Data.
Direct database access is the recommended path for downstream consumers (BI tools, ETL jobs, ad-hoc queries) that need the human-readable column names.
Direct database access
For all of its features ODD Platform uses PostgreSQL database and PostgreSQL database only. Database connection defining block would look like this:
Within PostgreSQL, ODD Platform database comprises two primary schemas:
public — this schema contains the essential resources of the ODD itself;
lookup_tables_schema — this schema contains all the lookup tables created by the user. Users can interact with these tables just like any other regular tables within the database.

Placing them in a separate schema is a matter of convenience, aimed to simplify the management of these tables particularly during migration like activities. This approach ensures a clear separation between user tables and service tables, allowing for independent handling and manipulation.
RBAC permissions
Lookup Table actions are gated by 9 permissions on three surfaces — table, definition (the column schema), and data (the rows). Assign these via the platform's Policies and Roles flow. The full permission list is regenerated from the OpenAPI spec under Permissions; the rows specific to Lookup Tables:
LOOKUP_TABLE_CREATE
Table
Creating a new lookup table (the +Add new flow).
LOOKUP_TABLE_UPDATE
Table
Renaming a lookup table or editing its description.
LOOKUP_TABLE_DELETE
Table
Deleting a lookup table.
LOOKUP_TABLE_DEFINITION_CREATE
Definition (columns)
Adding a column to an existing table's structure.
LOOKUP_TABLE_DEFINITION_UPDATE
Definition (columns)
Editing column metadata (rename, description, validation flags). The data type itself cannot be changed once set.
LOOKUP_TABLE_DEFINITION_DELETE
Definition (columns)
Deleting a column from the structure.
LOOKUP_TABLE_DATA_CREATE
Data (rows)
Inserting a new row.
LOOKUP_TABLE_DATA_UPDATE
Data (rows)
Editing an existing row's cell values.
LOOKUP_TABLE_DATA_DELETE
Data (rows)
Deleting a row.
The split lets operators grant edit-the-data without grant-edit-the-schema (a typical pattern for steward-curated reference lists), or grant create-the-table without grant-fill-the-data.
API reference
The full HTTP API for Lookup Tables is documented at API Reference → Reference Data — 16 endpoints across four groups (Table CRUD, Column CRUD, Row CRUD, Search) under /api/referencedata/, plus the LookupTableFieldType mapping notes and the per-endpoint LOOKUP_TABLE_* RBAC gating that ties back to the permissions table above.
Where to next
Master Data Management — the parent pillar landing; positions Lookup Tables within the broader MDM / Reference-Data Management surface and the Data Governance map.
Data Modelling — the sibling pillar for query examples and entity relationships.
Permissions — the canonical, regenerated-from-spec permission list (includes the 9 Lookup Tables rows above).
Configure ODD Platform — the Spring datasource keys (
spring.custom-datasource.*) the platform uses for both its own metadata and thelookup_tables_schema.
Last updated