Proposal: Typed relationships between concepts

[smgam29]

Summary
OKF currently expresses all concept-to-concept relationships as plain markdown links. This works well for navigation, but loses the semantic meaning of the relationship, for example, an agent reading a link has no way to know whether it represents a dependency, a replacement, an implementation, or a classification without parsing the surrounding text/content.

The problem in practice
I'm building a GraphRAG knowledge engine on top of a large enterprise SaaS documentation corpus (~46,000 markdown files). When extracting entities and relationships for the knowledge graph, I'm working with relationship types like implements, depends_on, replaces, part_of, triggers, and validates. These distinctions matter for how an agent traverses and reasons over the graph — a depends_on edge should be followed differently from a replaces edge. These ontologies will also vary depending on the proposed role of the consuming agent.

With OKF's current link syntax, all of that collapses to:

See [customers](/tables/customers.md).

The relationship type has to be inferred from context, which is lossy for agents and impossible to query structurally, especially when the consuming model has limited context or smaller parameters, for example in local processing scenarios. I understand a balance is required between verbosity and allowing for inference.

Precedent in the broader ecosystem
The Google Cloud Knowledge Catalog platform already has this concept at the service level: entry link types support synonym, related, definition, and schema-join, with explicit directionality (symmetric vs asymmetric) defined at the link type level. OKF is positioned as the portable, file-based counterpart to the managed catalog — but currently has no way to express the same relationship semantics that the platform already supports. Surfacing this in the format spec would close that gap and make OKF bundles portable carriers of the same semantic graph that Knowledge Catalog models internally.

A minimal proposal
Add an optional rel attribute convention to OKF cross-links — either as an extended markdown link attribute or as a structured links frontmatter field:

Option 1 — Frontmatter links block:

links:
  - target: /tables/customers.md
    rel: depends_on
  - target: /metrics/weekly_active_users.md
    rel: implements

Option 2 — Inline extended syntax (e.g. title-field convention):

[customers](/tables/customers.md "rel:depends_on")

Option 1 is more queryable and agent-friendly. Option 2 stays in the markdown body and preserves the current link model (my recommendation for now is 2 as it's just simpler).

Why this matters
OKF's stated goal is to turn a directory into "a graph of relationships richer than parent/child hierarchy." Typed relationships are what make a graph semantically navigable rather than just structurally navigable. Without them, OKF bundles are trees with shortcuts — not graphs in the knowledge-engineering sense.

This is a backward-compatible addition: bundles without rel annotations remain valid OKF. Consumers that don't understand rel ignore it. Consumers that do can use it for routing, traversal weighting, and structured querying.

Questions for maintainers

1. Is typed relationship support in scope for a future OKF version?
2. Is there a preferred extension mechanism for producers who need this today — additional frontmatter, a links block, or something else?
3. Should the spec recommend a standard vocabulary of relationship types, or leave that to producers? I'm imagining how relationship 'packs' or 'families' could provide some standards for common vectors (implementation guidance, technical content, legal wikis)
4. Are others hitting this in practice, particularly outside the BigQuery/data-catalog use case?

Thanks for considering!