Arda Domain Name (ADN)

Concepts¶

The state of the Arda System is composed of a collection of Bitemporal Records that, taken together, represent the complete information held by the system over time.

The system organizes these records into Entitites each of them representing the bitemporal evolution of a piece of information that is relevant to the representation
of the business domain (manufacturing, logistics and operations) that the system supports.

Entities are further grouped into Entity Types that define the schema of information contents common to all Entities of that Type. Entity Types can be further
specialized into Sub-Types that refine the information contents and behavior of the base Entity Type acting as Views or Lenses over the base Entity Type.
The complete set of Entities that belong to a Type is called a Universe.

Important

The concept of Sub-Type is not the same as Inheritance in Object-Oriented Programming but rather specializations or views of an underlying conceptual entity.
Some of these Sub-Types may actually include information contents that is part of other entities in the system to support certain use cases or behaviors, thus denormalizing
the strict partition of information in entities.

An example of this would be a Kanban-Card entity type with a details subtype that would include additional information about the Item entity that the Kanban Card refers to.

Note

Open Point: An extended interpretation of Sub-Types may include references to meta-entities related to the base entity type. As examples, the following subtypes may be defined:

history: A view that includes the complete bitemporal history of the entity instance
audit: A view that includes additional information about the operations that created or modified each record in the entity lineage.
draft: A view that includes unpublished or draft versions of the entity records.
query: A view that allows the specification and retrieval of a subset of entity instances based on extended criteria.
meta: A view that includes meta-information about the entity type itself, including audit and change history information.

These extended uses of the subtype are still under consideration.

Entity Types are in turn grouped into Domains and Sub-Domains that help organize the concepts in a manageable Information Model that
scales, from a System Engineering point of view, to handle the complexity of Arda’s business domain.

An Arda Domain Name (ADN) is a String value that can designate one of:

A Universe, representing the complete set of Entity Instances of a particular Entity Type, optionally seen through a particular Sub-Type lens.
Subsets of Entity Instances within a Universe, selected through additional criteria expressed as parameters in the ADN value.
An Entity Instance representing its complete lineage of records.
A specific Entity Record within the lineage of an Entity Instance.

ADN Syntax¶

The ADN syntax is based on the ideas from the standard for Uniform Resource Names (URN)

BNF Notation (Follows ABNF Standard RFC 5234)¶

The ADN syntax that the System accepts is defined by the grammar below with the following notes, not expressible as ABNF:

The Grammar defined is case-insensitive in the interpretation of ALPHA characters on input parsing, except in some
specific technology constraints imposed by the underlying infrastructure (e.g. S3 interpretation of keys is case-sensitive).
It is an error to use the reserved keys (rid, effectiveasof, recordedasof, version) in parameter definitions
other than for the expressly allowed cases in the f-parameter and q-parameter rules.
version is only an example of a possible version format that will be defined later.
The values of effectiveasof and recordedasof are to be interpreted as Unix Epoch time in milliseconds.

adn          = "adn:" [domain-path] ":" type-path ":" [entity-id]
               [ "?" q-parameter *( "&" q-parameter ) ]
               [ "#" f-parameter *( "&" f-parameter ) ]

domain-path  = domain *("/" SIMPLE-NAME)
domain       = "meta" / "system" / "asset" / "operation" / "transaction" / "business" / "oam"

type-path    = SIMPLE-NAME *("/" SIMPLE-NAME)

entity-id    = UUID

q-parameter  = parameter / ("rid=" UUID) / ("effectiveasof=" ULONG) / ("recordedasof=" ULONG)

f-parameter  = parameter / ("version=" VERSION)

; NOTE: The original grammar had an undefined 'VERSION' and 'ULONG'. 
; I am defining 'VERSION' as a generic string and 'ULONG' as a sequence of digits.
; Example definition for a version string following a lax Semver format.
VERSION      = 1*DIGIT ["." 1*DIGIT ["." 1*DIGIT]]

parameter    = key [ "=" value ]

; Except for reserved keys (see below), exclusion cannot be expressed in ABNF
key          = SIMPLE-NAME

reserved-keys = "rid" / "effectiveasof" / "recordedasof" / "version"

value        = url-encoded-string
// Lexical elements

SIMPLE-NAME  = 1*( ALPHA / DIGIT / "-" / "." )

url-encoded-string = 1*url-string-part
url-string-part    = URL_CHAR / "+" / pct-encoded
pct-encoded  = "%" 2(HEXDIG)

UUID         = 8HEXDIG "-" 4HEXDIG "-" 4HEXDIG "-" 4HEXDIG "-" 12HEXDIG
ULONG        = 1*20DIGIT

; Basic Character Groups (extended from Core ABNF, RFC 5234)
ALPHA        = %x41-5A / %x61-7A                             ; A-Z / a-z
DIGIT        = %x30-39                                       ; 0-9
HEXDIG       = DIGIT / "A" / "B" / "C" / "D" / "E" / "F"
               / "a" / "b" / "c" / "d" / "e" / "f"
ALPHA_LC        = %x61-7A                                    ; A-Z / a-z
HEXDIG_LC       = DIGIT / "a" / "b" / "c" / "d" / "e" / "f"

; Special Character Groups
URL_CHAR = ALPHA / DIGIT / "-" / "." / "~"

An visualization of this grammar follows. In case of discrepancies, the abnf is the authoritatively version.

Semantics¶

adn Prefix: Identifies the value as an Arda Domain Name.
domain: One of the top level domains defined in the Information Model
- meta: Entities that themselves are used to describe other Entities in the system.
- system: Entities that represent implementation resources, including meta-descriptors, configurations, network addresses, etc. It also includes the representation
  and support of external integration and communication protocols like EDI, etc.
- assets: Reference data and representation of resources that are used in the operation of processes supported by Arda’s system. They include
  item catalogs, business affiliates and companies, locations, etc.
- operations: Entities supporting or representing the elementary operations of manufacturing, logistics and material flow. They include Kanban Cards,
  Loops, stations, movements, manufacturing processes, demand and fulfillment signals, etc.
- transactions: The representation and support of complete business transactions like Orders, Demand, Receiving, Shipping, …
- business: Orchestration of higher level business processes and interaction with accounting and other business systems.
- oam: The entities representing and supporting the Operation, Administration and Maintenance of the Arda System itself. This Domain is further classified
  into subdomains of:
  - fault: Detection, Diagnosis and reaction to issues in the system.
  - configuration: Structure of the system, inventory, etc..
  - accounting: Cost tracking, assignment and management
  - performance: Monitoring and Performance metrics, SLAs, …
  - security: Access to the system, secrets, encryption, etc.
domain-path: Always starting with the top level domain, it may include additional segments representing subdomains. The domain path may be empty (optional), in which
case the type-path must be globally unique as it is the case with many Entity Types like item, currency, …
type-path: The non-optional name of an entity type. Entity Types are unique withing their parent domain or subdomain but frequently are globally unique. Additional segments in the
type-path represent subtypes as defined above.
entity-id: When present, it identifies a particular Entity Instance within the Entity Type Universe. The Entity Instance is identified by a UUID. In addition, when this value is present, the ADN identifies
a specific record within the lineage of the Entity Instance, determined by either the presence of the rid parameter, the presence of effectiveasof and/or recordedasof query parameters or by the system’s value of now()
at the time the ADN is resolved.
q-parameter: Additional parameters that refine the set of entities or records that the ADN represents. There are three special q-parameter values:
- rid: A UUID that identifies a particular record within the lineage of the Entity Instance identified by the entity-id. When both entity-id and rid are present, the ADN represents a specific record.
  if entity-id is not present, the system will still resolve the rid taking advantage of its global uniqueness. When both are present, they must identify a valid Lineage-Record pair. When rid is present
  in the query, all other parameters are ignored as the rid already identifies a specific record.
- effectiveasof: The effective bitemporal coordinate to use when resolving the ADN to a specific record. When not present the system will use it own local clock time to determine the value of now to use.
- recordedasof: The recorded bitemporal coordinate to use when resolving the ADN to a specific record. When not present the system will use it own local clock time to determine the value of now to use.
f-parameter: Additional parameters that help the user of the ADN interpret the value that the ADN represents.
- version: The special reserved f-parameter of version designates the version of the EntityType that
  is expected to be used when interpreting the information contents of the entity or record identified by the ADN. When not present, the client should interpret the latest published version of the Entity Type.
  The use of the version parameter is still under development.

Note

An open point is whether to allow ADN’s to represent partitions or shards of an Entity Type Universe as a way to facilitate the resolution of ADN’s to specific system locators.
This is left TBD at this time.

`Pinned` vs `Floating` References.¶

ADN’s are references to entities in the system and can identify either the complete lineage of versions of an entity or a specific bitemporal version of the entity.

As a shorthand, we call ADN’s Pinned when they point to a specific version record of the entity. These versions are immutable in the system
and are never deleted in the normal operation of the system (They can still be removed from the system through OAM operations for archiving, purging, etc..)
We call Floating ADN’s to those that point to complete entity lineages. The actual values of the entity records that will be accessed when the Entity name (ADN)
is used depends on external or contextual information to specify the bitemporal coordinates to be used in the context of the operation. When the contextual
coordinates are relative (e.g. now, latest, etc.) the actual record the ADN refers to may change depending on when the operation is executed or what other
contextual (e.g. another reference entity) is used.

Examples¶

Example ADN	Description
`adn:operations:kanban-card/details:6bfb5db2-86e6-4f2f-8894-ecd2371e692c?rid=9c2e0d8e-e8ab-4b36-943b-20ee0571697d#version=3`	Fully qualified ADN identifying a `details` view of a record of the `kanban-card` type in the `operations` domain identified with its `EId` and `RId`, it also specifies that the record corresponds to version 3 of the Entity Type
`adn::currency:c3246df2-7f46-4e2c-914e-0191ec26d04c`	The record of the `currency` entity identified by its `EId` at the bitemporal time of `now()` from the system perspective.
`adn::currency:27607d36-3384-4000-bb75-a5adf28d6dd3?effectiveasof=12345789`	The record of the `currency` entity instance identified by its `EId` with the given `effectiveasof` value and the `recordedasof` value taken from the system `now`
`adn::currency:?effectiveasof=123456&symbol=USD`	The set of Entity Records that have the value of `USD` for their property `symbol` at the bitemporal coordinates of the given `effectiveasof` and the systems `now()` as `recordedasof`
`adn::currency:`	The record for bitemporal coordinates of `now()` for each of the entities of the Entity Type `currency`

Illegal ADN Examples¶

Example ADN	Description
`adn:::`	No Entity Type specified
`adn:custom:tpe:`	`custom` is not a valid top level domain

ADN Resolution: Relationship to Operation addressing¶

Arda’s system is a microservice based architecture. Functionally Operations (e.g. Routes in the case of REST protocol) on the system are grouped in Services (Endpoints) and
Services are supported by Modules. Entity Instances are managed by specific Module Instances (Either one instance in the whole Shards)

At Runtime, Modules are deployed inside Components which are the actual running processes that execute the operations. Components
are bound to network addresses and ports, with associated protocol stacks (e.g. HTTP, gRPC, etc.) to communicate with other components and external systems.

ADN values don’t imply or constrain the addressing of operations in the system, although they are clearly related. Operations are frequently performed on a target ADN, sometimes
identifying a specific record, some other times specifying a Universe or a set of entities or records. The encoding of these target ADN values, their parameters and other operations
parameters is dependent on the particular protocol type. Arda’s system will develop standards and best practices for these encodings.

Implementation¶

The ADN Specification is implemented in:

ArdaDomainName class to provide the abstraction of ADN and its construction in different scenarios.
ArdaDomainNameSerializer and ArdaDomainNameStrictSerializer classes to provide serialization and deserialization from/to string representations.
ArdaDomainNameColumn to provide ADN columns, represented as Strings in the Kotlin Exposed ORM framework.