Reference Data

Reference data is one of the three main kinds of entities in the Arda system (alongside transactional data and historical data). It is information used to classify, categorize, or provide context for workflows, processes, transactions, and other data. Reference data is typically long-lived and changes slowly — changes are usually made as a consequence of an explicit user decision.

Entity Lifecycle

Every entity in the system has a lifecycle: the set of states and transitions that determine how the entity can change its information contents and how those changes are recorded. The lifecycle for reference data is designed to meet specific requirements around versioning, immutability, and auditability.

Requirements

Reference data in the Arda system must meet these requirements:

Requirement	Description	Example
Versioning	Users must be able to retrieve the value of any reference data entity at any point in the past.	A user can view the reference data values that applied when a sales order was accepted.
Immutable References	Each version of reference data must have a stable identifier for use by business processes.	A manufacturing operation can refer to fixed process sheets or units of measure.
Auditable	All changes must be recorded and reviewable, including the user, timestamp, data versions before and after, and an optional comment.	Regulatory compliance, product recalls, accounting audits.
Temporal Resilience	The system must track both when changes are made in the real world (effective time) and when the system is updated (recorded time), and maintain a consistent representation.	An auditor must be able to justify invoice amounts based on what the system contained at the time the invoice was issued, even if data was updated retroactively.
Staged Changes	The system must support staging changes so they can be reviewed and approved before becoming effective, and scheduled for a specific effective date.	A user may take multiple interactions to complete a reference data update, or multiple users may be involved in approval.

Reference Data Lifecycle

Reference data items pass through the following states:

State	Description
DRAFT	Created but not yet published. Visible only to the owner or a restricted set of users. Cannot be used in business processes except for testing.
PUBLISHED	Active and available for use in business processes, subject to regular access control. Versioning information is available.
ARCHIVED	No longer active. Cannot be used in business processes. Accessible only to users with access to historical data.
RETIRED	Permanently removed from active use. An archived item may be retired after appropriate retention periods.

State transitions:

DRAFT → PUBLISHED (publish)
DRAFT → ARCHIVED (archive without publishing)
DRAFT → DRAFT (edit while in draft)
PUBLISHED → DRAFT (edit, creates a new version)
PUBLISHED → ARCHIVED (archive)
ARCHIVED → DRAFT (edit, creates a new version)
ARCHIVED → retired

When in the PUBLISHED state, versioning information is available and the item can be used in business processes. The specific versions accessible to different users and processes depend on the business process and user privileges. For example, in normal use only the current version of a price reference datum can be used in a sales order, but certain users may access past or future versions for audits or exceptional business processes.

Relationship to Journaled Entities

Reference data entities are journaled entities. The journaling mechanism provides the audit trail, versioning, and immutable record access that the reference data requirements demand. The lifecycle states above are expressed through the entity’s metadata, while the history of state transitions is captured through the journal.

Excluded from this document: Transactional data lifecycle is described as TBD in the source document and will be added when defined.