Spec proposal: Use the markdown link "title" for richer link semantics in OKF

[wictorwilen]

Summary

OKF describes every link — cross-links (§5), index entries (§6), and citations
(§8) — using only the two-part markdown form [text](destination). Standard
markdown also allows an optional title:

[link text](destination "title")

OKF never mentions this third part. I propose recognizing the link title as an
optional, dual-purpose slot that carries (1) an optional machine-readable
relationship type and (2) free-form descriptive context. It is fully
optional, backward-compatible, requires no tooling, and degrades gracefully —
in keeping with OKF's minimal philosophy.

Motivation

The gap

§5.3 ("Link semantics") states:

The specific kind of relationship (parent/child, references, joins-with,
depends-on, etc.) is conveyed by the surrounding prose, not by the link
itself. Consumers that build a graph view typically treat all links as
directed edges of an untyped relationship.

So today every edge in an OKF knowledge graph is untyped. To learn that a
link is a foreign-key join versus a citation versus a "see also," a consumer
must parse the surrounding prose — brittle for agents and invisible to humans
until they read the sentence around the link.

The markdown title slot is the natural, standards-compliant place to attach
that semantic without inventing new syntax or frontmatter, and without
cluttering prose.

Why it's valuable

For humans

• Hover tooltips render in standard tools (GitHub, Obsidian, VS Code, most
  markdown viewers) with zero custom tooling — the link explains itself.
• Faster scanning: relationship intent is attached to the link, so a reader
  doesn't have to parse the surrounding sentence to know why it's there.
• Keeps prose clean — context that would otherwise be a parenthetical can live
  in the tooltip.

For agents

• Typed edges for free: build and traverse a typed knowledge graph without
  running NLP over prose to guess the relationship.
• Disambiguation: when a concept links to several others, the title tells
  the agent which is the join key, which is the source-of-truth, which is just
  "related."
• Cheap retrieval signal: titles are short, structured hints that improve
  ranking and routing.
• Refactor-stable: a title token like joins-with survives rewording of
  the surrounding sentence far better than prose phrasing.

Proposal

Recognize the markdown link title across all link contexts (cross-links, index
entries, citations). Two complementary uses, either or both:

1. Typed relationship (optional convention)

Use a leading token before an optional colon to denote an edge type; the
remainder (if any) is free-form context:

See the [customers table](/tables/customers.md "joins-with: on customer_id").

• Token before : → relationship type (joins-with).
• Text after : → descriptive context (on customer_id).
• The relationship vocabulary stays open and un-registered, exactly like
  type values in §4.1. Consumers MUST tolerate unknown relationship tokens.

A small non-normative starter set could be suggested (not mandated):
references, joins-with, depends-on, derived-from, part-of,
see-also, supersedes.

2. Descriptive context only

A title with no recognized token is treated as a pure human/agent tooltip:

See the [ingestion dashboard](https://example.com/dash "Live Airflow DAG for the orders pipeline").

Rules

• The link title is OPTIONAL. Absence is never an error.
• Consumers MUST tolerate links with no title, with a descriptive-only title,
  or with an unrecognized relationship token (treat as untyped + context).
• Titles carry no required vocabulary; they augment, never replace, prose.
• This is additive and backward-compatible — a minor version bump per §11.

Before / after

Before (untyped edge, intent only in prose):

| `customer_id` | STRING | Foreign key into [customers](/tables/customers.md). |

After (typed edge + context, prose optional):

| `customer_id` | STRING | FK into [customers](/tables/customers.md "joins-with: customer_id = customers.id"). |

Index entry (§6) gains a hover hint:

* [Orders](/tables/orders.md "part-of: sales dataset") - one row per order

Citation (§8) clarifies the source's role:

[1] [BigQuery schema](https://console.cloud.google.com/... "derived-from: authoritative schema export")

Suggested spec edits

• §5 (Cross-linking) — add a §5.4 "Link titles" subsection defining the
  optional title slot, the type: context convention, and the
  tolerate-unknown rule. Add a sentence to §5.3 noting titles MAY carry a typed
  relationship that lifts an edge from untyped to typed.
• §6 (Index Files) — note that index entries MAY include a title as a hover
  description (complementing the trailing - description).
• §8 (Citations) — note that citation links MAY use a title to describe the
  source's role/relationship.
• §9 (Conformance) — no new hard constraints; explicitly list
  "missing/unknown link titles" alongside the existing must-not-reject items.
• §11 (Versioning) — record as a backward-compatible minor addition.

Backward compatibility

• Existing bundles remain conformant unchanged.
• Renderers that ignore titles still display correct links.
• Agents that don't parse titles behave exactly as today (untyped edges).
• No new files, frontmatter keys, or tooling required.

[DeaconDesperado]

We've been using something quite similar via the mechanism of typed wikilinks, in our case often tied off to RDF ontologies via a property IRI as proposed in #98.