Typed relations
A plain link says two ideas are connected. A typed one says how — which makes it an assertion, and an assertion can be wrong.
What a relation is
A lens declares its own vocabulary of relations: investigated, authorized, derives from, contradicts. Each has a value (what you write), a label (what you read), a direction, and a colour.
You use one by writing it into a link: [[wg-the-tapes::investigated|The White House Tapes]]. The part before :: is the target, the part after is the relation, and anything after | is just the label a reader sees.
Relations are per lens, which is the point rather than a limitation. A historian's vocabulary and a novelist's vocabulary over the same material should not have to be the same vocabulary.
The test: read it back as a sentence
Before you type an edge, say it out loud as subject — relation — target. If that sentence is false, do not use that relation.
This sounds trivial and it is the single most useful habit on this page. Two real failures, from a lens whose relations were authorized, covered-up, funded, informed-on, investigated and reported-on:
| Written | Reads as | |
|---|---|---|
Sam Dash [[wg-ervin-committee::investigated]] | “Dash investigated the committee” | ✗ He was its counsel. |
Sam Dash [[wg-dean::informed-on]] | “Dash informed on Dean” | ✗ Dean was the informant. |
Neither was carelessness. The lens had no relationfor “served on” or “was counsel to”, so the nearest available one got used instead of none — and the result was an arrow pointing the opposite way from the truth, drawn in the same ink as every correct edge.
When no relation fits, use a plain link
A wrong typed edge is worse than an untyped one.An untyped edge says “these are connected”, which is true and useful and leaves the reader to supply the rest. A typed edge asserts something specific, and a wrong one is indistinguishable from a right one until somebody checks.
A lens with six relations makes an untyped link feel like a failure to classify. It is not. If you keep reaching for a relation that nearly fits, that is evidence your lens is missing one — which is worth knowing, and is a better outcome than a graph full of near-misses.
Direction
Every relation is either directed or symmetric, and the difference changes where you write it.
| Where the edge goes | |
|---|---|
| Directed | parent-of, authorized, investigated. Write it on the source only, pointing at the target. “Tywin parent-ofCersei” lives in Tywin's node. |
| Symmetric | allied-with, sibling-of, married-to. Write it on both endpoints. |
It is entirely fine to add a link purely to express a relation. The edge is the content.
What happens to an undeclared relation
Nothing bad. A ::relation the lens has not declared falls back to a plain edge, with a warning at import. The link still draws; it just stops making a claim.
That is the right failure direction and it is deliberate — the alternative would be inventing a relation nobody defined, which is exactly the “wrong edge that looks like data” problem arriving through a different door.
Weighted edges: a relation that carries a number
Some claims aren't just directional, they have a size. Owns is the clearest case: Vivendi owning 12% of a company and Microsoft owning 100% of it are both true, about different moments, and a graph that draws both the same way — a line, no number — has thrown away the part that matters.
Write the number after the relation, separated by =: [[atvi::owns=51|Activision Blizzard]]. Everything after the first = is kept verbatim, which is why officer-of=Chairman is just as valid as owns=51 — a value is not always a share, it can be a title sitting in the same slot.
owns=51 and owns=49 written to the same pair with no dates is not two edges, it is a contradiction — only the first is kept. Date them differently and that stops being true, which is what the next section is about.Spans: when a claim held
The paragraph above says Vivendi's 12% and Microsoft's 100% are both true “about different moments”. A value alone cannot say which moments, so the two collapse into a contradiction the graph has to pick a winner from. A span is how an edge says when it held, and it is written after the last @:
| Written | Means |
|---|---|
[[atvi::owns=51@2013-10-11..2016-01-05]] | Closed: held between those two dates. |
[[atvi::owns=100@2023-10-13..]] | Held since — no closing date yet. |
[[atvi::owns=12@..2016-01-05]] | Held until — the start was never established. |
[[atvi::owns=12@2013-10-11]] | A point: that day and no other. The ..is what makes a span open-ended. “As of 11 October” in ownership prose usually means “from then on”, so requiring the explicit ..is deliberate — a silent “and thereafter” is the kind of default that turns a typo into a claim. |
[[wg-nixon::chaired@1940-05-10..1945-07-26]] | Dates without a value. A span does not need a number to be worth having. |
Write the precision you actually have
“Vivendi exited in 2016” is often the most precise thing the record supports. A bound may therefore be a year, a month, or a day, and it is stored as the first day of the period named together with the precision it was claimed at — so @2016 is the year 2016, not the 1st of January.
| Written | Means |
|---|---|
@2016 | Somewhere in 2016. |
@2016-03 | Somewhere in March 2016. |
@2016-03-14 | That day. |
Widening a year to a manufactured January date would invent a day nobody can cite; refusing to accept 2016at all would refuse the fact. Carrying the precision does neither. It also changes what the checker can say: an imprecise bound makes a span's true extent a range rather than a fact, so overlaps are flagged only where they are unavoidable given what was actually claimed.
@ still survives — officer-of=Chairman@Large keeps its @, because the text after the last @ is read as dates only when it really parses as a date range. An impossible date like 2013-02-30 is refused rather than rounded.Shapes: what kind of graph a relation forms
Declaring a relation gets you a coloured arrow. On its own that doesn't tell the app what a wrong graph would look like — a person with two managers and a person with one draw identically. A shape is what turns a picture into a claim you can be wrong about.
| Shape | What it catches |
|---|---|
tree | At most one outgoing edge per node, no cycles. reports-to, subsidiary-of— a second manager or a second parent company is the classic “one of these is wrong.” |
chain | One in, one out — a succession. Two successors to the same office is a contradiction, and so is a loop. |
dag | No limit on edges, but no cycles either. controls — A controlling B controlling A is a mistake or a shell game, either way worth flagging. |
weighted | Carries a value that is a share of the target. Stakes flowing into one entity that total over 100 get flagged — see above. |
many | No constraint, and the default. parent-of and casts are many however tree-shaped one case looks, because a person can have three children and a film five leads. |
_lens.md is still yours to push even if a sentence in it breaks its own declared shape; the app flags it and draws it anyway, and leaves the correction to you. Omitting the column is always safe: an unrecognised or absent declaration lands on many, the least constrained shape there is.A flagged violation shows as a count on the graph itself, with the full list under Lens settings → Figures.
down / invert — when the sentence points the wrong way to draw
Owns and subsidiary-ofpoint opposite ways in prose for the same fact. “Microsoft owns Activision Blizzard” puts the source on top; “Blizzard is a subsidiary of Activision Blizzard” puts the source underneath — both are a plain source→target edge, and nothing in the data tells them apart.
The house default is to author a hierarchy from the superior — write parent-company-ofin the parent's own file, and it draws right without help. invert exists for the relation that only reads naturally from below: mark it, and the app flips the edge before laying out a chart, so subsidiary-of can stay the sentence a person actually writes without silently inverting the picture.
What a shape draws
Declaring a shape does more than turn on a check. Any relation that is not many is treated as hierarchical, and the lens gains a hierarchy chart under Lens settings → Figures: holders across the top, what they hold beneath, and every edge carrying whatever value you wrote on it.
Three things it draws that an org chart usually will not. An edge that had to be turned around to make the picture acyclic is dashed and warning-coloured rather than quietly straightened — a loop in an authority graph is either an error or a genuinely reciprocal tie, and both are worth seeing. Anything in the lens that no hierarchical edge touches goes to an unplaced tray with a count, because a chart that showed only what it could place would report steady progress at every stage of an investigation, including the beginning. And a lens whose relations are all many gets a chart that says so, rather than a blank rectangle.
Effective ownership, when a stake runs through a chain
A second figure sits beside the chart, and it exists because a percentage on an edge stops being the whole answer as soon as somebody owns through something they already own. If A owns 51% of B and B owns 60% of C, there are two true answers about what A has in C, and they are different numbers:
| Reading | Answer | The question it answers |
|---|---|---|
| Control | 60% | Crossing half means B is controlled, so B’s holdings count in full. This is the rule sanctions regimes use. Is this controlled? |
| Economic | 30.6% | 0.51 × 0.60, the finance answer. No threshold, no jurisdiction. How much of this do they own? |
Both are right, which is why the figure shows them side by side rather than picking one. A chart showing only control overstates a minority holder’s economics; one showing only economics understates control, and would miss exactly the structures layering is designed to hide.
Declaring your vocabulary
In lens settings, or in _lens.md if the lens is vault-authoritative:
- Start small. Three relations you will actually use beat nine you will misapply. You can always add one.
- Name them as verbs from the subject's side — investigated, not investigation. It makes the sentence test automatic.
- Watch for the missing one. If two nodes keep wanting an edge you have no word for, that word is the next relation to add.
- Add a shape once a pattern is obvious. Most relations are honestly
many— the ones worth declaring are the ones you already know should never fork or loop.
Edges a model proposed
Weaving asks a model to find connections between nodes you already have, and everything on this page applies double to what comes back — a model reaching for the nearest available relation is exactly how both failures above happened.
Woven edges are marked as provisional rather than mixed in with the ones you drew, so you can tell them apart while you check them. Generate and weave.
Related
- Lenses, nodes and links — where relations sit in the model.
- The paste format — the four link forms, exactly.
- Groups and families — the other half of a lens's vocabulary.