Resolving relationships
Entities rarely stand alone. A person is employed by an organization, owns a policy, belongs to a household. A company owns subsidiaries. Relationships make those links first-class, governed data rather than something inferred at query time.
Relationships versus attributes
Relationship types, each carrying the cardinality and direction the resolver enforces.
The decision that matters most when modelling: is the related thing something you master?
| The related thing is… | Model it as | Why |
|---|---|---|
| Mastered — it is an entity you keep and govern | A relationship | The related entity owns its own data. Copying it onto this record guarantees the copies drift. |
| Not mastered — you keep no record of it | An attribute | An emergency contact you never master should not force you to invent a person entity. |
Storing a link as both a relationship and a denormalized attribute means two copies of one fact, and they will diverge. Choose one.
The resolution problem
Source systems rarely know the platform's identifiers. They reference the other side of a relationship by whatever they hold — a tax identifier, an account number, a registration code:
{
"employee": "E-4471",
"employer_tax_id": "12-3456789"
}
That tax identifier has to become a link to a governed organization entity. Doing it naively fails in two directions: the employer may not have been loaded yet, and the identifier may match more than one candidate.
The platform handles this with assertions. Each source's claim is recorded as an assertion in its own right, and a resolver turns assertions into canonical edges when — and only when — they can be resolved unambiguously.
An assertion that cannot be resolved yet is not lost and not guessed at. It waits, and is retried as more data arrives.
| Assertion state | Meaning |
|---|---|
| Pending | The referenced entity has not been found yet |
| Resolved | A canonical edge exists |
| Ambiguous | The natural key matched more than one candidate — a person decides |
| Conflicted | The target was found, but the edge could not be created — most often a cardinality rule blocked it |
This is why relationships survive out-of-order loading: assertions record what each source said, independently of whether the platform could act on it yet.
Effectivity
Relationships carry an effective period, so a link that ends is closed rather than deleted. Asking who owned an asset last March returns the right answer.
When a fact changes — an asset sold, an employment ended — the previous window closes and a new one opens. The history stays intact.
Interaction with merging
When two entities merge, relationships pointing at the absorbed record are re-pointed onto the survivor, deduplicating where both sides already shared a counterpart. Unmerging restores the original arrangement.
Next
Last verified against commit 315eb047 (2026-08-03)