GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
Convention for maintenance signals — freshness, confidence, contradiction (additive under §4.1)
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
OKF nails the static format. What I believe is missing is a convention for the signals a knowledge base needs once it's *living* — once something's writing to it, reading from it, and trusting it weeks later. Three of them: how fresh a fact is (`timestamp` tells you when content last *changed*, not when it was last *verified* still true), how much you trust a given claim, and what happens when two concepts disagree (links are untyped, and the spec's quiet on conflicting content — no `contradicts`/`supersedes`).
Candidly, I opened this before I'd read the rest of the week's trust threads properly, and there's more overlap than I gave credit for — so let me reframe. I don't think this should be a competing proposal; the individual pieces are already further along in other hands, and I'd rather point at them than restate them:
- On **confidence**, #151 (@K4uP) is the real version — a reliability axis with production behind it. Mine should defer to that.
- On **freshness**, #97 (elevate `timestamp` for staleness) and #120 (keeping bundles healthy as they evolve) are already carrying it; my `last_verified` is the same idea.
- On **provenance** more broadly, there's already a cluster of threads (verification, SOURCES, citation); the over-time / decay angle rides alongside that work, not into it.
So what I think is actually left that's differentiated, once you strip the overlap, is two things. First, the framing: freshness, confidence, and contradiction are really one *maintenance* surface, not three unrelated asks — and it'd help to treat them as a coordinated convention (or an `EXTENSIONS.md`-style registry) so they don't land piecemeal. Second, a contradiction edge I haven't seen elsewhere: #151's conflict signal is about competing claims *within* a concept, but I'm after the *cross-concept* case — a typed link where one concept supersedes or contradicts another (an "HQ moved to Austin" note quietly obsoleting "HQ in Denver"). That's the rot that actually kills a living KB — not "how sure am I about this claim" but "this whole concept is wrong now because that one replaced it." Feels closest to #148's typed relationships.
None of this needs a core change — §4.1 already lets producers add keys and tells consumers to preserve them, so it's legal OKF today; the only thing missing is *agreed* names.
For what it's worth, I'm not theorizing — I've run a multi-domain, human-authored KB on these signals for months, and Throughline (an OKF reader/writer, https://github.com/inkxel/throughline) does freshness + confidence + contradiction end to end. Happy to be a second worked example next to #151's.
So mostly a question: is there appetite to treat maintenance signals as one coordinated convention — this issue holding the integration view and the cross-concept edge, with confidence and freshness deferring to #151/#97? Or is lifecycle just out of scope for v0.1?
Contributor guide
Research direction
Read §4.1 first, then compare the related proposals in #151, #97, #120, and #148 to separate existing work from the remaining cross-concept contradiction case. Use Throughline as the cited worked example, and define done as a decision on whether coordinated maintenance signals and typed supersedes/contradicts links belong in v0.1 or an extensions registry.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100