Skip to main content

ADR-009 - Relation Kind Vocabulary

  • Status: Accepted
  • Decision Date: 2026-07-23
  • Deciders: PIES Design Team
  • Category: Data Model, Ontology

Context​

LINKAGE messages express relationships between assets in PIES. The relation_kind field classifies the semantic meaning of a linkage. Without an explicit vocabulary, implementers may invent arbitrary descriptors, leading to inconsistent and ambiguous edge semantics in the undirected graph. A controlled vocabulary of symmetric terms ensures that relationship meaning is unambiguous and preserves the integrity of the undirected topology (where edge direction is not meaningful).

Decision​

Constrain relation_kind to a finite vocabulary of symmetric, verb-based descriptors. The initial vocabulary includes: SELF, SPLITS, MERGES, and RELATES. These terms preserve symmetry (no directional bias). The relation_kind field is mandatory for all LINKAGE messages. Implementers must declare classification intent upfront rather than omitting the field.

Rationale​

Symmetric verbs (or nouns like SELF) ensure that the graph topology remains undirected and unambiguous. Unlike directional verbs (e.g., "supersedes," "depends_on"), symmetric terms work equally well regardless of which asset appears first in the linkage. This design protects against directional confusion and maintains clarity during graph traversal. Requiring explicit relation_kind on all linkages eliminates ambiguity and ensures graph traversal engines can rely on consistent semantics for all edges.

Assumptions​

  • SELF, SPLITS, MERGES, and RELATES capture the essential linkage semantics for initial PIES scope.
  • All LINKAGE messages must carry an explicit relation_kind from the controlled vocabulary.
  • relation_kind is case-sensitive and always uppercase.
  • Graph traversal engines can rely on relation_kind being present and meaningful on all edges.

Options Considered​

  • Optional classification: Implementers choose whether to provide relation_kind. Simpler initially but loses semantic clarity and creates inconsistency. Rejected due to risk of unclassified edges.
  • Directional verbs (depends_on, supersedes, etc.): Clearer semantics but introduces directional ambiguity in an undirected graph. Rejected to preserve topology integrity.
  • Mandatory symmetric verbs (chosen): SELF, SPLITS, MERGES, RELATES. All linkages must declare their classification. Preserves undirected semantics while ensuring consistent, unambiguous edge semantics. Allows future expansion without breaking existing links.

Consequences​

Positive​

  • Symmetric vocabulary prevents directional confusion and maintains graph integrity.
  • All linkages carry explicit semantic meaning; graph traversal engines can rely on consistent edge classification.
  • No ambiguous or unclassified edges reduce implementation errors and query inconsistency.
  • Specification is focused and stable for initial PIES scope.

Negative​

  • Implementers must decide on classification for every linkage; requires clarity on relationship semantics upfront.
  • Implementers cannot express directional semantics; some use cases may require workarounds (e.g., expressing directionality in asset_kind or payload context).
  • New relation_kind values require formal ADR governance to maintain vocabulary integrity.
  • Graph traversal requiring direction must infer it from asset types, not edge properties.

References​

  • ADR-004 establishes undirected graph semantics as a core principle.
  • ADR-005 defines LINKAGE as a distinct message kind.