GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

Proposal: typed/confidence-tagged links: frontmatter extension for OKF concepts

Open
#183 2 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.