lookupTable

Concept layer — frozen. The Lookup Tables generic. Nothing here is written by a normal playbook run; a project's own feature analysis is the live document and takes every edit. This layer names no project and links to none — the dependency runs one way, from an application to its concept.

Feature: Lookup Tables

Entity: lookupTable

Description: The lookup tables store values that are not tightly bound to the core application logic. These values are configurable at runtime — when you add, remove or update them in the database, the changes are automatically reflected across the application without requiring any code changes.

Entity Type: Table — lookupTables

Attribute Name	Description	Data Type	Default Value	Required (= Nullable)	Unique	Format	Validations	Index	Example
id	Unique identifier for the record	UUID v7	Auto-generated (in code)	Yes	Yes	-	Must be a unique identifier	Primary Key	123e4567-e89b-12d3-a456-426614174000
lookupKey	The identifier used to retrieve the corresponding lookup values from the lookup table.	String	-	Yes	No	lt.key	Must not be an empty string	name: idx_lookupTables_active_lookupKey, type: btree	lt.education
lookupValue	The actual value of the lookup table instance returned from the API.	String	-	Yes	No	-	Must not be an empty string	-	cs
attributes	Extra attributes unique to this lookup table	JSONB	-	No	No	JSON	-	-	{ "isEuCountry": true }
position	Used for ordering when the lookup table is displayed in a dropdown	Integer	-	No	No	Should be a positive number	-	-	1
active	Indicates whether the lookup table is active or not	Boolean	True	Yes	No	-	-	name: idx_lookupTables_active_lookupKey, type: composite btree	true
createdAt	Timestamp of entity creation	timestamp with time zone	now() — assigned in code	Yes	No	ISO 8601 — YYYY-MM-DDTHH:mm:ss.SSSZ	-	-	2025-03-16T18:00:00Z
updatedAt	Timestamp of last entity update	timestamp with time zone	now() — assigned in code	Yes	No	ISO 8601 — YYYY-MM-DDTHH:mm:ss.SSSZ	-	-	2025-03-16T18:00:00Z
deletedAt	Timestamp of entity soft delete. Once set (that is, once it is non-null), this value is immutable and cannot be changed.	timestamp with time zone	-	No	-	ISO 8601 — YYYY-MM-DDTHH:mm:ss.SSSZ	-	-	null
createdBy	Identifier of the author who created this record.	String	-	Yes	No	type:actor	-	-	user:c2d3f586-1c9a-4f5f-b9ae-45f2c4f69f7e
updatedBy	String that identifies the author who last updated this record.	String	-	Yes	No	type:actor	-	-	system:migration

Example Data

INSERT INTO lookupTables (id, lookupKey, lookupValue, attributes, position, active,
                          createdAt, updatedAt, deletedAt, createdBy, updatedBy)
VALUES
  ('018fa51f-fd9f-7ccd-b7ec-74c755d5fd31', 'lt.locale', 'cs-CZ', null, 1, true,
   '2025-04-18T18:45:00+02:00', '2025-04-18T18:45:00+02:00', null, 'seed:init', 'seed:init'),
  ('018fa51f-fda0-7e61-a1b4-86d842ae27b3', 'lt.locale', 'en-GB', null, null, true,
   '2025-04-18T18:45:00+02:00', '2025-04-18T18:45:00+02:00', null, 'seed:init', 'seed:init');

Constraints & Indexes

• (lookupKey, lookupValue) is unique among live rows.
• The locale spelling in the example (cs-CZ) is illustrative, not a convention: a project fixes one spelling for locale values and uses it in the catalogue and in every label key — see Translations.
• Ordering is by position, nulls last.
• Index lookupKey together with active — an ordinary composite btree.