GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

Convention for maintenance signals — freshness, confidence, contradiction (additive under §4.1)

Open
#158 11 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

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.