Proposal: YAML flow-map properties on typed relationship links

[deepdb-ch]

Summary

Extend the typed relationship link conventions discussed in #101, #148, and #183 by allowing an optional YAML flow mapping after rel:<type> in a Markdown link title.

[Customers](/tables/customers.md "rel:depends_on {confidence: inferred, weight: 0.8}")

This represents a Source–Type–Target relationship with zero or more properties while remaining an ordinary Markdown link.

Proposed syntax

relationship-title = "rel:" relationship-type [SP yaml-flow-mapping]

Examples:

[Orders](/tables/orders.md "rel:writes_to")
[Orders](/tables/orders.md "rel:writes_to {confidence: inferred}")
[Legacy API](/apis/legacy.md "rel:supersedes {effective_since: '2026-08-01', reason: migration}")

Semantics:

• The containing concept is the relationship Source.
• The Markdown destination is the relationship Target.
• The token after rel: is the producer-defined Relationship Type.
• The optional YAML flow mapping contains Relationship Properties. These properties belong to the relationship, not to either endpoint.
• Omitting the mapping preserves the existing rel:<type> form.
• Property values retain their YAML types.
• The optional value must parse as a mapping, rather than a scalar or sequence.
• Canonical writers should emit standard YAML spacing, for example {confidence: inferred}.
• Consumers that do not implement this convention continue to treat the title as opaque link metadata and the link as an ordinary OKF relationship.

Relationship types and property keys remain producer-defined. Consumers should preserve unknown types and properties and ignore those they do not understand.

Motivation

The existing proposals cover related pieces but do not provide a general inline representation for relationship properties:

• Spec proposal: Use the markdown link "title" for richer link semantics in OKF #101 proposes using the Markdown link title for a relationship type and descriptive context.
• Proposal: Typed relationships between concepts #148 proposes typed relationships using either structured frontmatter or an inline rel:<type> title.
• Proposal: typed/confidence-tagged links: frontmatter extension for OKF concepts #183 proposes target, rel, and confidence in a frontmatter links: collection.
• Budget-aware assembly for OKF: optional edge priority levels #139 demonstrates another independent relationship property, level.

Once producers need both confidence and level—or fields such as role, weight, effective_since, or provenance—adding one dedicated syntax rule per field does not scale. A YAML flow mapping supplies a small, extensible property bag using syntax already familiar to OKF authors.

Compatibility and round-tripping

This proposal does not introduce new Markdown syntax. It only defines an optional convention inside the standard Markdown link title.

A property-graph consumer can map the example losslessly to a relationship annotation such as:

[:DEPENDS_ON {confidence: inferred, weight: 0.8}](/tables/customers.md)

Likewise, a structured consumer can project it to a frontmatter representation without inventing field-specific mappings:

links:
  - target: /tables/customers.md
    rel: depends_on
    properties:
      confidence: inferred
      weight: 0.8

The inline link should remain the source of truth unless a future OKF convention explicitly defines synchronization with a frontmatter index.

Open questions

1. Should Relationship Properties allow all YAML values, or only scalar values and scalar sequences?
2. Should duplicate property keys be invalid for deterministic consumption?
3. Should the specification define the normalized links: projection shown above, or leave that to producers?
4. Should human-readable context remain a separate link-title suffix, or simply be represented as a property such as description?

[drapermcp]

Data point from a large producer, in favour of the rel:<type> {props} title convention, with two requests.

We run a knowledge corpus of ~1.58M OKF v0.2 documents with a typed relationship layer of ~2.9M edges (statutory cross-references, shared-concept links, and a six-dimension analytical enrichment we call 6Q). Today those edges live in sidecar JSON, which means a generic OKF consumer reads the documents and loses the graph. We have just published a sample bundle (Wyoming criminal code, 264 nodes, 696 typed links: https://github.com/drapermcp/nkb-legal-okf-sample) using exactly the proposed syntax — [§ 6-1-104](/nodes/wyoming-criminal-section-6-1-104.md "rel:sequential-section {strength: 0.85}") — and it round-trips through plain markdown tooling with nothing lost, which is the property we care about.

On the open questions:

1. Scalar-only values would cover everything we emit (type, confidence, weight, effective date). Nested mappings inside a link title get unreadable fast; keep the title human-legible.
2. Duplicate keys: prohibit. Producers can always normalise.
3. A normalised frontmatter projection is worth specifying — an optional relationships: list in frontmatter ({to, rel, props}) that a producer MAY emit alongside the inline links. Large graphs need one place a consumer can read without parsing prose; inline links alone do not scale to nodes with hundreds of edges.
4. Descriptive context stays in prose, not in the props. The link title is for machine-readable typing; the surrounding sentence is for people.

One further request: reserve a way to state which relationship vocabulary a bundle uses (rel_vocabulary: in the bundle index.md, pointing at a document that defines the types). Untyped-but-labelled links are only useful across bundles if the labels are declared somewhere.

Reference: technical note on running large corpora as OKF supersets, DOI 10.5281/zenodo.21861595 (CC-BY).

[drapermcp]

Follow-up from the same producer, with a measurement and a second shipping pattern.

We ran a frozen 16-item retrieval pilot on the Wyoming sample (264 nodes, two engines, blind grades). Citation lookup saturates on a flat OKF bundle — no typed links, no extra keys. What the flat reader cannot do is list recorded neighbours as a set, or treat “no recorded connection” as a finding rather than a search miss. The typed rel: links in the node (this issue’s convention) are what made that neighbourhood listing work.

A caution on how not to ship the rest of a large graph: if the producer dumps the whole edge table as one JSON on the same search path as the documents, agents grep the dump until the tool budget dies and lookup fails. The repair that worked is one small neighbor file per node (neighbors/<id>.json), read for that node only. That pattern is now in the sample repo: https://github.com/drapermcp/nkb-legal-okf-sample/blob/main/PATTERN.md

So: inline rel: titles for documents a markdown tool already understands; local neighbor files for reverse lookup and for nodes whose degree would make a Related section unreadable. The frontmatter relationships: projection we asked for in the earlier comment still solves the same scaling problem inside a single file.

Still in favour of scalar-only props, prohibit duplicate keys, and a bundle-level rel_vocabulary:.

Technical note: What a Flat OKF Reader Loses, DOI 10.5281/zenodo.22739602 — sibling of 10.5281/zenodo.21861595.