GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
Proposal: typed/confidence-tagged links: frontmatter extension for OKF concepts
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
## Summary
OKF v0.1 links between concepts are plain markdown links — no type, no provenance/confidence. This makes it hard for a producer to express "concept A `writes_to` concept B, inferred with medium confidence" versus "A `references` B, stated explicitly" — both currently render as the same undifferentiated `[B](../b.md)` link.
We ran into this building [graphify-okf-bridge](https://github.com/asphwathpc/graphify-okf-bridge), a bridge between [Graphify](https://github.com/Graphify-Labs/graphify) code knowledge graphs (typed, confidence-scored edges: `imports_from`, `inherits`, `reads_from`, …) and OKF bundles. Exporting a Graphify graph to OKF and re-importing it losslessly requires *some* place to carry edge type and confidence — OKF v0.1 has no such field.
## Proposal
A backward-compatible frontmatter extension (relies on §4.1's "bundles can carry arbitrary extra frontmatter keys" — no spec change required to *adopt* it, but documenting it as a convention would let independent producers/consumers interoperate on typed edges):
```yaml
links:
- target: tables/orders.md
rel: writes_to # relation vocabulary is producer-defined
confidence: inferred # extracted | inferred | ambiguous
```
Kept alongside the existing plain markdown link in the body (`## Connections` or similar), so untyped consumers (Obsidian, `viz.html`, any tool that doesn't know this convention) are unaffected and continue to see a normal link. Typed-aware consumers get the extra structure.
## Why raise it here
- It's fully additive — no breaking change to §9 conformance (parseable frontmatter + non-empty `type`; everything else stays soft).
- We have a working, tested implementation to point to as a concrete example: [`spec/MAPPING.md` §2 rule E7](https://github.com/asphwathpc/graphify-okf-bridge/blob/main/spec/MAPPING.md) (export) and §3 rule I3/I4 (import, including the fallback for bundles that only have plain links).
- OKF v0.1 explicitly invites external producers/tooling; a documented `links:` convention seems like a natural place for the spec (or a companion "conventions" doc) to standardize something multiple producers will independently reinvent otherwise.
Happy to contribute a PR with a spec section or a `conventions/` doc if that's a useful direction — wanted to open this as a discussion first since it's a design choice, not just a bug.
Contributor guide
Research direction
Start by reading §4.1 and §9 of the OKF v0.1 specification, then compare the proposed convention with spec/MAPPING.md §2 rule E7 and §3 rules I3/I4 in the linked bridge. Determine whether this belongs in the main spec or a conventions document; done means the chosen format and plain-link fallback are documented clearly enough for independent producers and consumers.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown, yaml
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100