Arda Domain Name (ADN)

An Arda Domain Name (ADN) is a string value that can designate entities and entity types within the Arda system. It is the canonical addressing scheme for the Arda information model.

Concepts

The Arda system’s state is composed of bitemporal records that, taken together, represent the complete information held by the system over time. These records are organized into entities, each representing the bitemporal evolution of a piece of information relevant to the business domain.

Entities are grouped into Entity Types that define a shared information schema. Entity Types can be further specialized into Sub-Types that act as views or lenses over the base type. The sub-type concept is not inheritance in the object-oriented sense — sub-types may include denormalized information from related entities to support specific use cases.

The concept of Sub-Type may be extended to include: history (complete bitemporal history), audit (audit trail), draft (unpublished versions), query (filtered subsets), and meta (meta-information about the type). These extended uses are still under consideration.

Entity Types are grouped into Domains and Sub-Domains that organize the information model at a manageable scale.

An ADN can designate:

• A Universe — the complete set of entity instances of a particular Entity Type, optionally through a Sub-Type lens
• A Subset of entity instances within a Universe, selected through additional criteria
• An Entity Instance — the complete lineage of records for a specific instance
• A specific Entity Record within the lineage of an instance

ADN Syntax

The ADN syntax is inspired by the Uniform Resource Names (URN) standard (RFC 8141).

Structure

adn:<domain-path>:<type-path>:<entity-id>[?q-parameter[&q-parameter...]][#f-parameter[&f-parameter...]]

Where:

• domain-path: Optional. Starts with one of the top-level domain names. May include additional subdomain segments separated by /. When omitted, type-path must be globally unique.
• type-path: Required. Name of an entity type. Entity types are unique within their parent domain but frequently globally unique. Additional segments represent sub-types.
• entity-id: Optional. UUID identifying a specific entity instance.
• q-parameter: Query parameters refining the set of entities or records. Special reserved values: rid, effectiveasof, recordedasof.
• f-parameter: Fragment parameters helping the user interpret the ADN value. Special reserved value: version.

Top-Level Domains

Domain	Description
meta	Entities describing other entities in the system
system	Implementation resources, configurations, network addresses, and external integration protocols
assets	Reference data and representations of resources used in operations: item catalogs, business affiliates, locations
operations	Elementary operations of manufacturing, logistics, and material flow: kanban cards, loops, stations, movements
transactions	Complete business transactions: orders, demand, receiving, shipping
business	Higher-level business process orchestration and interaction with accounting systems
oam	Operation, Administration, and Maintenance of the Arda system itself, organized into sub-domains: fault, configuration, accounting, performance, security

Semantics

• When entity-id is present, the ADN identifies a specific entity instance. The actual record returned is determined by the rid parameter (if present), or by the effectiveasof and recordedasof parameters, or by the system’s value of now() at the time of resolution.
• rid (query parameter): UUID identifying a specific record within the entity instance’s lineage. When present, all other bitemporal parameters are ignored.
• effectiveasof: The effective bitemporal coordinate. When absent, the system uses its local clock.
• recordedasof: The recorded bitemporal coordinate. When absent, the system uses its local clock.
• version (fragment parameter): The version of the Entity Type schema expected when interpreting the entity’s information contents.

Pinned vs Floating ADNs

As with entity references:

• An ADN with both entity-id and rid present is a pinned ADN — it points to an immutable, specific record.
• An ADN with only entity-id (and optionally bitemporal query parameters) is a floating ADN — the record it resolves to may change depending on when and how the ADN is evaluated.

ADN Examples

ADN	Description
adn:operations:kanban-card/details:6bfb5db2-86e6-4f2f-8894-ecd2371e692c?rid=9c2e0d8e-e8ab-4b36-943b-20ee0571697d#version=3	Pinned ADN: a details view of a specific kanban-card record, version 3 of the Entity Type
adn::currency:c3246df2-7f46-4e2c-914e-0191ec26d04c	Floating ADN: the currency entity instance at now()
adn::currency:27607d36-3384-4000-bb75-a5adf28d6dd3?effectiveasof=12345789	Floating ADN with explicit effective time; recorded time defaults to now()
adn::currency:?effectiveasof=123456&symbol=USD	Universe subset: currency records with symbol=USD at the specified effective time
adn::currency:	Universe: all currency entity records at now()

Relationship to Operation Addressing

ADN values describe what entity or set of entities an operation targets. They do not constrain how operations are encoded in specific protocols. The encoding of ADN values as path segments, query parameters, or message payload attributes depends on the protocol (REST, gRPC, event bus). See Entity References for how ADN concepts map to specific protocol encodings.

Excluded from this document: The ABNF formal grammar and the implementation class names (ArdaDomainName, ArdaDomainNameSerializer, ArdaDomainNameColumn) belong in the Current System section.