Skip to content

ADR-006 — Canonical Relationship Vocabulary

Status

Accepted

Context

The UC-BoK Knowledge Graph connects entities across domains using typed edges. Without a closed, canonical relationship vocabulary, the graph would accumulate ad-hoc relationship names that cannot be queried consistently, validated mechanically, or reasoned about semantically.

Decision

UC-BoK uses a closed canonical relationship vocabulary. All edges in the Knowledge Graph must use a relationship name from the ALLOWED_RELATIONSHIPS set defined in graph/build_graph.py and SPEC-006.

Foundational rules (from SPEC-006):

  1. Relationship names use lowercase_snake_case in the graph and lowercase-kebab-case in YAML.
  2. Every relationship has a defined source entity type and target entity type.
  3. The graph enforces referential integrity: all target nodes must exist (or be auto-created as referenced stubs).
  4. owns relationships define the primary containment hierarchy (used for ownership traversal and orphan detection).
  5. Derived (inverse) relationships may be auto-generated but are never the source of truth.
  6. New relationship types require a SPEC-006 amendment and a ALLOWED_RELATIONSHIPS update — they cannot be added ad hoc.

Canonical relationship set (at time of acceptance)

belongs_to, owns, implements, publishes, manipulates, produces, requires, references, changes, supports

Extended in later ADRs with RA and EXP relationship types.

Consequences

  • check_graph.py validates every edge against ALLOWED_RELATIONSHIPS and fails if unknown relationships are found.
  • New entity connections must be modelled using existing vocabulary where possible; new vocabulary requires an explicit decision.
  • Graph consumers (query engine, generators) can enumerate all relationship types exhaustively.