Entities

Entities are the main building blocks to describe the structure of the Arda System’s state.

Common Characteristics¶

All Entities share a set of characteristics:

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 also have other ways to uniquely identify them based on their contents but even if it is not the case, they still have an identity that is unique and immutable.
Information Contents: Entities have information contents that can be described as a Dictionary value with their identity one of the elements of the dictionary. The Class of an entity is determined by the Type of the Dictionary that describes its information contents.
Metadata: Some entities may have additional metadata that describes the entity itself of the context in which it should be evaluated. While this metadata can be considered part of the entity’s information contents, it often is related to the entity’s behavior in the system, like what tenant they belong to, lifecycle information (draft, published, etc.) or other considerations that can be handled by cross-cutting concerns in the system that do not necessarily apply to all entities.
Universe: A set of entities with the same Class that is managed as a group is defined to be a Universe. A Universe may impose additional constraints on the entities it contains, such as uniqueness criteria, etc. A Universe also defines a scope where entities can be searched for. Note that there may be multiple Universes for a given Class and Universes do not need to be disjoint. For example, a Universe may be defined for all entities of a given Class that are owned by a specific Tenant, while another Universe may be defined for all entities of the same Class that are owned by a different Tenant. The Universe is used to define the scope of operations on the entities it contains.

Types of Entities¶

There are three main kinds of entities:

Reference Data: Information that is used to classify, categorize or provide context for workflows, processes, transactions and other data. It includes data about the system itself, its users and specific manufacturing and material flow information. Reference data is typically static and does not change frequently. Reference Data is usually long-lived and changes slowly. Changes are usually made as a consequence of an explicit decision or action by a user.

Transactional Data (TBD): Information associated with a specific execution of a business process or workflow. Its information contents changes frequently while the execution of the process is in progress. Transactional Data becomes archived or historical data once the process is completed. When the process is completed, transactional entities are no longer mutable.

Historical Data (TBD): Information that is no longer actively used in business processes but is kept for reference or compliance purposes. It is typically archived and may be accessed for audits, reports, or historical analysis. Historical data is immutable and can only be viewed, not modified. This data represents events, results, or states produced by the execution of business processes or workflows.

Each of these kinds of entities have different lifecycles and requirements. A common requirement to Reference Data and Transactional Data is for the system to keep track of the changes that those entities undergo and record enough information about those changes to support audits, compliance requirements and forensic analysis. These requirements are supported through Journalled Entities.

Universes¶

A Universe is a set of entities that share the same Class and are managed as a group. The operations that a Universe may vary, but they commonly include:

Create: Add a new Entity to the Universe. A Universe may be able to access Entities that are not created through this operation (the result of other low level processes, or in the case of overlapping Universes).
Read: Retrieve an Entity from the Universe by its unique identity. A Universe may support multiple versions of Read operations with varying levels of detail or other variations. A Read operation may also provide access to deleted Entities under special conditions.
Update: Modify the information contents of an Entity in the Universe.
Delete: Remove an Entity from the Universe given its identity (and other overlapping Universes). This operation should not physically remove the information about the Entity instance, but rather mark it as deleted and prevent it from being accessed by normal business processes.
List: Retrieve a list of Entities in the Universe that match a Filter. In addition to the Filter, this operation may also support pagination and sorting. The amount of information returned by a List operation may vary in the same way as the Read operation. Similarly, a List operation may also provide access to deleted Entities under special conditions. Universes may also support specialized versions of List operations for specific use cases or that impose additional filters or sorting criteria.
Count: Retrieve the number of Entities that the Universe has access to that match a Filter. This operation may support counting deleted Entities under special conditions.

A Universe also implements behaviors that affect how its operations behave:

A well-defined UniversalCriteria which is a Filter that is applied to all operations on the Universe to restrict access to the Entities it accesses. This UniversalCriteria can be used to enforce ABAC conditions, tenancy access and similar use cases. The UniversalCriteria is defined by the system at design time and cannot be modified by users or other processes, although it can be parametric based on the context in which the Universe is created in the system and the operation is executed (e.g., dependent on user properties).
Validation Rules for each operation that are applied to the Entities affected by the operation considering the context and the specific parameters of the operation.

Entity Class Model¶

Common Inter-Entity Relationships¶

Entities can relate to other entities to capture real-world relationships between concepts or objects. Relationships are implemented by Entities holding properties that are References to other entities. The main relationship patterns are:

Identity or 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.

Note that at the Class level, there may be multiple extensions for the same Entity Class, but at the instance level, a given Entity always has either none or one extension of a given Class assigned to it

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

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 the aggregated entities is possible through the aggregation entity but not the other way around.

Implemented by an Array (ordered) or Set (unordered) of references in the primary entity (A) to the aggregated entities (B). Or through optional references from B to A. The choice may be influenced by the specific dependency relationships between A and B.

Composition or Parent-Child¶

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

Implemented by an Array (ordered) or Set (unordered) of references in the primary entity (A) to the child entities (B) or by a required reference in the child entity (B) to the parent entity (A), or both. A Universe for B entities maybe defined for each A entity allowing access only to the children of the given parent entity.

Binary Association (m:n)¶

An Entity is related to another entity with any cardinality basis. The relationship is implemented by a separate entity that holds references to both entities.

It can be implemented in a number of ways depending on cardinalities and other requirements. In the general case of many-to-many relationships, it is common to implement it using a third entity that holds references to both entities as in:

If the intersection entity (AB) has additional information aside from the references to A and B, it is also known as a Ternary Relationship and represented also as:

Three entities are related forming a ternary relationship.

For implementation, particularly in relational databases, it is common to use a fourth entity that simply holds references to the other three.

Note that this can be extended to n-ary relationships.