Should OKF support ontology-linked typed relationships beyond fixed lifecycle edges ?

[brendonhumphreys]

Context

OKF v0.2 §6.1 says a link from concept A to B "asserts a relationship", with the specific kind conveyed by surrounding prose rather than the link itself; consumers building a graph view "typically treat all links as directed edges of an untyped relationship." Producers can carry any additional keys in frontmatter, but the spec does not define a shape for producer-declared typed edges.

PR #195 opens this door narrowly by proposing two reserved lifecycle edges (supersedes, contestedBy) that live in frontmatter and carry defined semantics. That PR is deliberately minimal — asymmetric vs symmetric, no inverse alias, resolution kept in log.md — and does not aim to model relationships whose vocabulary comes from an external domain (a dbt lineage graph, a bigquery-owner mapping, a governance ontology).

This discussion asks a design question that is complementary to #195, not competing with it: should OKF grow a first-class story for typed relationships whose predicate names come from an external vocabulary and whose meaning is defined outside the OKF spec?

The gap in concrete terms

A producer that has already committed to a domain vocabulary — an OWL/TTL ontology, a schema registry, a taxonomy — currently has three unappealing options for expressing typed edges in an OKF bundle:

1. Prose only. The # Joins heading convention already works, but the edges are not machine-queryable without NLP over the body.
2. Ad-hoc frontmatter keys. joins_with:, owned_by:, derived_from: invented per producer, unstandardised across bundles, opaque to consumers.
3. Wait for the vocabulary of interest to become a reserved OKF predicate. Unrealistic for anything domain-specific.

None of these support a consumer that wants to load a bundle graph, ask "what edges exist between concepts X and Y, and where in the source is the assertion supported?", and get a deterministic answer.

Sketch of one possible direction

Not a proposal — just a shape to react to.

---
type: BigQuery Table
title: Customer Orders
# ontology declared at bundle root (index.md) or per-file
predicate_vocabulary: https://example.org/ontology/data-lineage
relationships:
- predicate: dl:derivedFrom # compact IRI, resolves via vocabulary
target: /tables/raw-orders.md
evidence:
source: dbt-manifest
section: manifest.json#nodes.orders
statement: >-
dbt manifest declares `orders` as depending on `raw_orders`.
assertion: explicit
---

Design points worth debate before any spec text:

• Vocabulary binding — how does a bundle declare which vocabulary its predicates come from (single, list, per-file)? Or is the compact-IRI prefix declaration enough?
• Evidence discipline — should evidence be required on every relationship, or optional like everything else in §5?
• Consumer contract — does the spec say anything about how consumers should treat unknown predicates, or is that left to the vocabulary?
• Overlap with okf: propose typed relationship edges (supersedes, contested_by) (#148) #195 — do supersedes and contestedBy sit in a reserved okf: namespace under this model, or stay separate?
• Validation — does the spec define how a consumer would verify predicates against a vocabulary, or is that a separate reference implementation (as the reference validator being contributed today does for base conformance)?

Questions for maintainer

1. Is this a direction OKF wants to explore, or should typed relationships stay minimal — reserved lifecycle edges only, everything else in prose?
2. If yes: is your preference a new spec section (§6.x), a separate optional profile, or a proposal doc under okf/proposals/ first?
3. Are there design constraints from the reference-agent side that would rule out any part of the sketch above?
4. Is there existing thinking (previous issues, draft docs, offline conversations) I should read before drafting anything concrete?

If the direction is welcome, I would draft a proposal doc plus fixture bundles as a follow-up PR. If it isn't, that's useful too — the reference validator I'm about to send has a --profile extension point where domain-specific tooling can live without touching core spec.

Not-goals of this discussion

• Not asking to rewrite §6.1
• Not proposing a fixed enumeration of predicates
• Not competing with okf: propose typed relationship edges (supersedes, contested_by) (#148) #195
• Not asking OKF to adopt any specific ontology framework (OWL/RDF/SKOS/plain-YAML)

[deepdb-ch]

PGM 0.4.0 Public Draft 1 may be useful as a concrete answer to the carrier part of this design space. It is an external semantic profile of OKF 0.2, CommonMark, and YAML, not a proposal for OKF to own domain vocabularies.

PGM maps every OKF Concept Link occurrence to one outgoing relationship. When the normal Markdown link title is a complete YAML flow mapping, that entire mapping becomes the relationship properties. A non-empty string type is retained in the map and is also exposed as the relationship's graph-element type:

[Raw orders](/tables/raw-orders.md "{type: 'dl:derivedFrom', assertion: explicit, evidence: {source: dbt-manifest}}")

A non-PGM consumer still sees an ordinary OKF/CommonMark link, and an absent, ordinary, or invalid PGM title never removes the baseline OKF relationship. Unknown types and properties are preserved.

This builds on the link-title direction discussed in #101, but uses a complete structured map rather than a type: context token. Compared with #183's parallel frontmatter index, the properties stay attached to the exact link occurrence. PGM deliberately does not define ontology binding, inverse/symmetry rules, evidence policy, or the lifecycle behavior in #195; those can remain named vocabularies or profiles above the carrier.

The review-ready PGM 0.4.0 snapshot includes a reference processor, executable tests, deterministic JSON/Cypher projections, and a 46-concept/124-relationship Ada fixture. There is also an interactive viewer.

If this looks useful, I would be happy to contribute a small interoperability fixture applying PGM to the BigQuery example in this discussion before suggesting any normative OKF change.

[deepdb-ch]

Rather than duplicate the proposal across the related threads, I am tagging their original authors here: @wictorwilen (#101), @smgam29 (#148), and @asphwathpc (#183).

PGM's narrow claim is about carrier semantics: an ordinary Concept Link occurrence plus a structured property map in its Markdown title, with type both retained as a property and exposed structurally. It is intended to carry, not replace, the vocabulary, lifecycle, retrieval, or evidence semantics being developed in those threads. I would value your view on whether this representation composes cleanly with the respective proposals.