Entities

Entities are the main building blocks for describing the structure of the Arda system’s state.

Common Characteristics

All entities share four characteristics:

1. Identity: Each entity has an identity that is immutable and unique within the system, independent of the rest of the information it contains. Entities may have additional ways to identify them based on their contents, but even if that is not the case, they still have an identity that is unique and immutable.

2. Information Contents: Entities have information contents that can be described as a Dictionary value with their identity as one of the elements. The class of an entity is determined by the type of the dictionary that describes its information contents.

3. Metadata: Some entities have additional metadata describing the entity itself or the context in which it should be evaluated. This metadata is often related to the entity’s behavior in the system — which tenant it belongs to, lifecycle information (draft, published), or other cross-cutting concerns that do not necessarily apply to all entities.

4. Universe: A set of entities with the same class that is managed as a group is called a Universe. A Universe may impose additional constraints such as uniqueness criteria and defines the scope within which entities can be searched. Multiple Universes may exist for a given class and they do not need to be disjoint.

Types of Entities

There are three main kinds of entities:

• Reference Data: Information used to classify, categorize, or provide context for workflows, processes, transactions, and other data. It includes system metadata, user and tenant information, and specific manufacturing and material flow data. Reference data is typically long-lived and changes slowly. Changes are usually made as a consequence of an explicit user decision. See Reference Data for lifecycle details.

• Transactional Data (TBD): Information associated with a specific execution of a business process or workflow. Its contents change frequently while the execution is in progress. Once the process is completed, transactional entities become archived or historical data and are no longer mutable.

• Historical Data (TBD): Information no longer actively used in business processes, kept for reference or compliance. Historical data is immutable and can only be viewed, not modified.

A common requirement shared by Reference Data and Transactional Data is that the system must keep track of changes and record enough information to support audits, compliance, and forensic analysis. This is supported through Journaled Entities.

Universes

A Universe is an access point to a collection of entities that supports CRUD operations. Universes commonly include:

• Create: Add a new entity to the Universe.
• Read: Retrieve an entity by its unique identity. Multiple variants may exist with different levels of detail. Deleted entities may be accessible under special conditions.
• Update: Modify the information contents of an entity.
• Delete: Mark an entity as deleted and prevent normal access. The entity record is not physically removed.
• List: Retrieve entities matching a filter, with support for pagination and sorting. Deleted entities may be included under special conditions.
• Count: Retrieve the number of entities matching a filter.

Universes also implement:

• A UniversalCriteria — a filter applied to all operations that restricts entity access. This can enforce attribute-based access control (ABAC), tenancy, and similar use cases. The UniversalCriteria is defined at design time and cannot be modified by users, though it can be parametric based on context.
• Validation Rules for each operation, applied considering the operation context and parameters.

Entity Class Model

Inter-Entity Relationship Patterns

Entities relate to other entities to capture real-world relationships. The main patterns are:

Identity / Delegation (Properties Extension)

An entity is related to another entity on a one-to-one or one-to-none basis as an extension of its information contents. At the class level there may be multiple extensions for the same entity class, but at the instance level a given entity always has at most one extension of a given class.

Implemented by either an optional reference from the primary entity to the extension, or a required reference from the extension to the primary entity, with a separate Universe or query used to locate the extension.

Aggregation

An entity acts as an aggregate of other entities. The lifecycle of the aggregate entity is independent of the lifecycle of the aggregated entities. Access to aggregated entities is possible through the aggregation entity but not the reverse.

Implemented by an Array (ordered) or Set (unordered) of references in the primary entity to the aggregated entities, or through optional references from the aggregated entities to the primary entity.

Composition / Parent-Child

An entity acts as a whole with respect to other entities that are its parts. The lifecycle of the parent limits the lifecycle of the child entities — if the parent is deleted, the children are also deleted. Access to child entities is possible through the parent, and it may also be possible to access the parent through the child.

Implemented by an Array or Set of references in the parent entity to child entities, by a required reference in the child to the parent, or both. A Universe for child entities may be defined for each parent, restricting access to the children of the given parent.

Binary Association (m:n)

An entity is related to another entity with any cardinality. In the general many-to-many case, it is common to implement the relationship using a third entity (intersection entity) that holds references to both.

If the intersection entity carries additional information beyond the two references, the relationship is also known as a ternary relationship:

A ternary relationship (where a third entity C is also related) can also be represented as:

For implementation, particularly in relational databases, it is common to use a fourth entity that holds references to all three:

This pattern extends to n-ary relationships.