Reference Relations
Cross-entity traceability relations and their graph semantics in NexoGraph.
Reference relations are directed graph edges that connect entities from different root collections. They form the backbone of NexoGraph's traceability model, enabling coverage analysis and impact assessment across the entire metamodel.
Only entities with canParticipateInReferenceRelations: true may appear as a source or target in a reference relation: Stakeholder, Need, Requirement, User, UserStory, CustomerFeature, and SystemCapability. Most need relations filter candidates by type, so stakeholder relations target Need.type = STAKEHOLDER and user relations target Need.type = USER. The need-informs-system-capability and need-refines-into-stakeholder-requirement relations accept both need types.
Cardinality
All reference relations have n:m cardinality, so any number of source entities can be linked to any number of target entities.
Defined Relations
stakeholder-has-stakeholder-need
A Stakeholder declares that they have a particular stakeholder-scoped Need.
| Property | Value |
|---|---|
| Relation ID | stakeholder-has-stakeholder-need |
| Graph relationship type | HAS_STAKEHOLDER_NEED |
| Source entity | Stakeholder |
| Target entity | Need (type = STAKEHOLDER) |
| Cardinality | n:m |
| Invalidated roots (source) | STAKEHOLDER_DEFINITION |
| Invalidated roots (target) | STAKEHOLDER_NEEDS |
| Source revision direction | OUTGOING |
| Target revision direction | INCOMING |
Traceability meaning: Links stakeholder definitions to the needs they own or express.
user-has-user-need
A User persona declares that they have a particular user-scoped Need.
| Property | Value |
|---|---|
| Relation ID | user-has-user-need |
| Graph relationship type | HAS_USER_NEED |
| Source entity | User |
| Target entity | Need (type = USER) |
| Cardinality | n:m |
| Invalidated roots (source) | USER_DEFINITION |
| Invalidated roots (target) | USER_NEEDS |
| Source revision direction | OUTGOING |
| Target revision direction | INCOMING |
Traceability meaning: When a user persona is revised, all linked user needs are marked as requiring review (OUTGOING from User). Conversely, when a user-scoped need changes, all users that declared it are flagged (INCOMING to User).
user-tells-user-story
A User persona tells (i.e. is the author of) a UserStory.
| Property | Value |
|---|---|
| Relation ID | user-tells-user-story |
| Graph relationship type | TELLS |
| Source entity | User |
| Target entity | UserStory |
| Cardinality | n:m |
| Invalidated roots (source) | USER_DEFINITION |
| Invalidated roots (target) | USER_STORIES |
| Source revision direction | OUTGOING |
| Target revision direction | INCOMING |
Traceability meaning: Links user personas to the agile stories they own. Useful for persona-level coverage reports.
user-story-expresses-user-need
A UserStory expresses (i.e. addresses) a user-scoped Need.
| Property | Value |
|---|---|
| Relation ID | user-story-expresses-user-need |
| Graph relationship type | EXPRESSES |
| Source entity | UserStory |
| Target entity | Need (type = USER) |
| Cardinality | n:m |
| Invalidated roots (source) | USER_STORIES |
| Invalidated roots (target) | USER_NEEDS |
| Source revision direction | OUTGOING |
| Target revision direction | INCOMING |
Traceability meaning: Closes the loop between needs and stories. A user need not covered by any story appears as a coverage gap. A story not tied to any need may be out of scope.
need-informs-system-capability
A stakeholder-scoped or user-scoped Need informs a SystemCapability.
| Property | Value |
|---|---|
| Relation ID | need-informs-system-capability |
| Graph relationship type | INFORMS |
| Source entity | Need (STAKEHOLDER or USER) |
| Target entity | SystemCapability |
| Cardinality | n:m |
| Invalidated roots (source) | STAKEHOLDER_NEEDS, USER_NEEDS |
| Invalidated roots (target) | SYSTEM_CAPABILITIES |
| Source revision direction | OUTGOING |
| Target revision direction | INCOMING |
Traceability meaning: Connects needs to the capabilities they shape. A capability with no informing need may be ungrounded, while a need with no downstream capability may indicate an implementation coverage gap.
customer-feature-enabled-by-system-capability
A CustomerFeature is enabled by a SystemCapability.
| Property | Value |
|---|---|
| Relation ID | customer-feature-enabled-by-system-capability |
| Graph relationship type | ENABLED_BY |
| Source entity | CustomerFeature |
| Target entity | SystemCapability |
| Cardinality | n:m |
| Invalidated roots (source) | CUSTOMER_FEATURES |
| Invalidated roots (target) | SYSTEM_CAPABILITIES |
| Source revision direction | OUTGOING |
| Target revision direction | INCOMING |
Traceability meaning: Connects customer-visible features to the capabilities that realize them. A feature without an enabling capability is a delivery coverage gap, while a capability with no enabled feature may need an upstream justification check.
need-refines-into-stakeholder-requirement
A stakeholder-scoped or user-scoped Need refines into a stakeholder-scoped Requirement.
| Property | Value |
|---|---|
| Relation ID | need-refines-into-stakeholder-requirement |
| Graph relationship type | REFINES_INTO |
| Source entity | Need (STAKEHOLDER or USER) |
| Target entity | Requirement (reqType = STAKEHOLDER) |
| Cardinality | n:m |
| Invalidated roots (source) | STAKEHOLDER_NEEDS, USER_NEEDS |
| Invalidated roots (target) | STAKEHOLDER_REQUIREMENTS |
| Source revision direction | OUTGOING |
| Target revision direction | INCOMING |
Traceability meaning: Shows which stakeholder requirements formalize upstream stakeholder or user needs. A requirement without an upstream need may lack elicitation evidence.
stakeholder-requirement-satisfied-by-system-capability
A stakeholder-scoped Requirement is satisfied by a SystemCapability.
| Property | Value |
|---|---|
| Relation ID | stakeholder-requirement-satisfied-by-system-capability |
| Graph relationship type | SATISFIED_BY |
| Source entity | Requirement (reqType = STAKEHOLDER) |
| Target entity | SystemCapability |
| Cardinality | n:m |
| Invalidated roots (source) | STAKEHOLDER_REQUIREMENTS |
| Invalidated roots (target) | SYSTEM_CAPABILITIES |
| Source revision direction | OUTGOING |
| Target revision direction | INCOMING |
Traceability meaning: Connects formal stakeholder requirements to the system capabilities that satisfy them. A requirement with no satisfying capability is a downstream coverage gap.
Full Traceability Chain
The relations define one shared need-centered traceability path:
This enables:
- Forward traceability - from a stakeholder, user persona, or customer feature, find the needs, requirements, stories, and capabilities attributed to them.
- Backward traceability - from a need, requirement, story, feature, or capability, find the upstream stakeholder, user, or customer context.
- Coverage analysis - detect needs and requirements with no upstream owner or downstream capability coverage.