Entity References

Concepts¶

An Entity Reference refers to the information that enables a part of the system to access an entity to inspect its public data or to
request actions on it. Entity References are themselves Values that can be stored, transmitted and
processed by different parts of the system.

`Pinned` vs `Floating` References.¶

Entities in the Arda system as Journalled in a bitemporal sense. References to entities can identify either
the complete lineage of versions of an entity (Floating Reference) or a specific bitemporal version of the entity (Pinned Reference).

Pinned references can rely on the fact that the entity version they point to will not change over time. Using Floating references requires
specifying the bitemporal coordinates to identify the specific version of the entity to access. In particular, when using Floating references
with Now time coordinates, the values or the entity properties may change depending on when the entity is accessed, or can even be deleted.

Entity Reference Structure and Information contents.¶

Regardless of the representation (data type) used to encode an Entity Reference, the information contents can be expressed using
a standardized URI structure as defined below.

Schema¶

The protocol that can be used to access the entity through this reference.

Possible Values:

https: For Rest based access using HTTPS protocol, typically V 1.1.
grpc: For gRPC based access using HTTPS/2 protocol.
eventbus: For Arda’s system event bus based access. In this case, the reference points to a listener on the event bus (TBD).
local: For local access within the same component.
contextual: The rest of the URI needs to be interpreted by the user of the reference.

Authority:¶

The Endpoint where the entity can be accessed. All requests/messages to the entity need to be addressed to this authority.

UserInfo MUST NOT be used in the authority section of the URI.

The authority part of the URI is MANDATORY except for the contextual schema.

Possible Values:

For https schema: A valid Host name or IP address that is Globally resolvable in the Internet. No port number should be specified. The default port 443 will be used.
For grpc schema: A valid Host name or IP address that is resolvable within the K8s cluster where the component runs. No port number should be specified. The default port 50001 will be used.
Components running on K8s, by convention in the Arda system, run on namespaces named as <partition>-<component>, e.g. prod-operations. The authority for
a gRPC URI of a reference should be constructed using ONLY the component name, e.g. operations. Components are NOT allowed to access entities outside their partition.
For eventbus schema: The address of the listener on the event bus (TBD). Event Bus is also partition scoped, so the authority should be constructed using ONLY the component name, e.g. operations.
For local schema: “local”
For contextual schema: The authority, if present, needs to be interpreted by the user of the reference

Path¶

The unique identifier of the entity within the authority’s domain.

Possible Values:

For https schema: A relative URL path (no leading slash) that represents the REST route to access the entity with the following path segments:
- module: The name of the module (service) that manages the entity (e.g. item, kanban-card, order, etc.) it must be URL friendly.
- resource or entity-type: The type of the entity among the ones managed by the module. It must be URL friendly. In many cases, the module may manage only
  one type of entity and the module and resource segments may have the same value, even in this case BOTH segments MUST be present.
  A module manages a collection of entity instances of a given resource or entity-type.
- One of:
  - {local-eid}: (Floating References) The local unique identifier of the entity represented as a UUID string. This is the identifier of the whole bitemporal lineage of the entity.
    see query parameters below for how to specify a specific bitemporal version of the entity.
  - {local-eid}/rid/{local-rid}: (Pinned References) The local unique identifier of a specific bitemporal version of the entity represented as a UUID string. Note that not all modules or resources
    may support complete functionality to address specific bitemporal versions of an entity as they offer the capability to access through the bitemporal lineage only.
  - other: Other path segments may be defined by the module managing the entity to support operations that address the complete collection of entities managed
    by the module like creation of new entities, querying, etc. This is out of scope for defining the Entity Reference Structure.
For grpc schema: A relative URL path (no leading slash) that represents the access route through the gRPC service that is the endpoint to access the entity-type
capabilities.
- gRPC service: A unique name within the authority part of the URI that identifies the gRpc service that manages the entity. It can be
  the same as the module/resource combination used in the https schema or use a different naming convention (tbd).
- One Of:
  - {local-eid}: (Floating References) The local unique identifier of the entity represented as a UUID string. This is the identifier of the whole bitemporal lineage of the entity.
    gRPC service operations will accept parameters to specify a specific bitemporal version of the entity. (TBD whether this will be handled through request attributes
    or will be part of the standard message payload).
  - {local-eid}/rid/{local-rid}: (Pinned References) The local unique identifier of a specific bitemporal version of the entity represented as a UUID string. Note that not all gRPC services
    may support the same operations based on rId addressing as the ones based on eId.
  - other: Other path segments may be defined by the gRPC service managing the entity to support operations that address the complete collection of entities managed.
    This is out of scope for defining the Entity Reference Structure.
For eventbus schema: The path segment structure is TBD as it depends on the design of the event bus based communication pattern. It will follow similar conventions as
the https schema for the default listener for an entity type, but an entity type may define multiple listeners for different functionality, so the overall structure is TBD.
For local schema: When using the local schema, the path segment needs to be interpreted by the user of the reference. The segments are:
- {service}: A unique name within the component that identifies the local service that manages the entity. It can be represented by a language type name or other language dependent
  meta-information that enable reflective access to the service instance that manages the entity.
- One Of:
- {local-eid}: (Floating References) The local unique identifier of the entity represented as a UUID string. This is the identifier of the whole bitemporal lineage of the entity.
  service operations will accept parameters to specify a specific bitemporal version of the entity.
- {local-eid}/rid/{local-rid}: (Pinned References) The local unique identifier of a specific bitemporal version of the entity represented as a UUID string. Note that not all local services
  may support the same operations based on rId addressing as the ones based on eId.
For contextual schema: When using the contextual schema, the path segments need to be interpreted by the user of the reference. E.g. the code using the reference may know the
entity type or the Service to invoke and how to invoke it to access the entity. The path segments are one of:
- {local-eid}: (Floating References) The local unique identifier of the entity represented as a UUID string. This is the identifier of the whole bitemporal lineage of the entity.
- {local-eid}/rid/{local-rid}: (Pinned References) The local unique identifier of a specific bitemporal version of the entity represented as a UUID string. Note that not all modules or resources
  may support complete functionality to address specific bitemporal versions of an entity as they offer the capability to access through the bitemporal lineage only.

Additional Path Segments¶

Endpoints managing entities may define additional path segments to support operations, selectors or other capabilities. These are out of scope for defining Entity References.

Some examples that may become standardized as part of other specifications are:

history: to access the bitemporal history of an entity.
Some crud operations like read or delete that don’t require additional information to execute.
meta to retrieve meta-information about the entity (TBD).

## Query, Header, Attribute Parameters

Reference Parameters¶

An entity reference is completely defined by the schema, authority and path segments and this is enough for most use cases. There is an edge use case
for Floating References when the entity has been deleted at the bitemporal coordinates that the request specifies. In this case, it is useful
to add a parameter to specify whether the request should return a not found or it should return the last version of the entity at deletion time.

This is very infrequent use case so the default for all references is to return not found, but Floating references may include a includedeleted parameter with
value of true to indicate that the reference will always return the last version of the entity if the entity has ever existed in the system.

Additional Parameters used in requests or messages addressing an entity.¶

Although parameters may be defined by each service managing the entity, there are standard parameters to refine addressing an entity, particularly when using eId based addressing.
These parameters are NOT currently part of an Entity Reference, but they may need to be part of requests to the service managing the entity.

tenantid: A UUID representing the tenant that the entity belongs to. This is mandatory for all regular user requests. System level requests may send a special value to gain access to
all tenants data. Details are still TBD.
- This is encoded in a Header for https schema.
- Encoded in the ApplicationContext or the entity metadata for local schema
- TBD for other schemas.
effectiveasof: A timestamp representing a Unix epoch in milliseconds that specifies the effective time dimension of the bitemporal version of the entity to access. If omitted, the
server will use the current time in its local clock as the effective time.
- Encoded as query parameter for https schema.
- Encoded in the EntityRecord data structure for local schema. For local schema, the datatype Timecoordinates represents both effective and recorded time coordinates.
  and the service operations explicitly accept these parameters where applicable.
- TBD for other schemas.
recordedasof: A timestamp representing a Unix epoch in milliseconds that specifies the recorded time dimension of the bitemporal version of the entity to access. If omitted, the
server will use the current time in its local clock as the recorded time.
- Encoded as query parameter for https schema.
- Encoded in the EntityRecord data structure for local schema. For local schema, the datatype Timecoordinates represents both effective and recorded time coordinates.
  and the service operations explicitly accept these parameters where applicable.
- TBD for other schemas.

Although out of the scope of this specification, other standard query parameters that services may define:

For mutation operations:
- Author: The unique identifier of the user on whose behalf the mutation is executed.
- optime: A timestamp representing a Unix epoch in milliseconds that specifies the effective time of any resulting entity versions created by the operation.
  NOTE that the current system (202512) is not consistent in using either operationtime or effectiveasof for this purpose. If omitted, the server will
  apply its own current time as the effective time for the resulting entity versions.
- requestId: A UUID representing the unique identifier of the request that triggered the mutation operation. This is used for idempotency and tracing.
  NOTE The current system (202512) has very limited use of this parameter.

Entity References

Concepts¶

Pinned vs Floating References.¶

Entity Reference Structure and Information contents.¶

Schema¶

Authority:¶

Path¶

Additional Path Segments¶

Reference Parameters¶

Additional Parameters used in requests or messages addressing an entity.¶

Comments

`Pinned` vs `Floating` References.¶