GoogleCloudPlatform / GoogleCloudPlatform/open-knowledge-format
Proposal: `imported` — attribute a concept taken from another bundle without inheriting its trust
- Dominant language
- HTML
- Stars
- 467
- Forks
- 35
- Avg merge
- 9m
- Merged PRs (30d)
- 1
Description
Raised after implementing an OKF **reader** in [Roteiro](https://github.com/OffeneDatenmodellierung/Roteiro), which already emits v0.2 bundles. Writing was straightforward; reading is where we hit something the format cannot express.
## Problem
**A consumer that imports a concept from another bundle and later emits its own has no honest way to describe it.**
Trust tiers are derived from `verified` (§5.3): absent → unverified, non-human actors → machine-confirmed, a `human:` actor → human-reviewed. So when bundle **B** imports a concept from bundle **A** and re-emits it, B must pick one of three, and each misstates the tier:
1. **Copy A's `verified` verbatim.** B's bundle now asserts `human:alice` verified this concept *in B*. She did not; she verified it in A. B has laundered someone else's confirmation into its own.
2. **Drop `verified`.** A concept a human reviewed in A becomes unverified in B — a silent downgrade of exactly the signal the tiers exist to carry.
3. **Re-verify with B's own actor.** B claims a confirmation it never performed; if the concept was unverified in A, this promotes a guess to machine-confirmed.
There is no fourth option, and the choice is forced on every consumer that both reads and writes.
The consequence compounds: B's bundle is itself consumable, so a third reader **C** cannot distinguish "B verified this" from "B copied A's claim". Whichever option B took, the error propagates and is unrecoverable downstream — the information needed to correct it was never written.
## Why `sources` does not cover this
`sources` is the closest existing key, and we looked at it first. Each entry takes `resource` (required), optional `id` and `title`, and the credibility signals `author`, `usage_count`, `last_modified`.
It describes **materials a concept draws on**, and it deliberately carries no verification events — its signals are objective and countable, which is the right design for what it does. So `sources` can record *that* an upstream bundle was consulted. It cannot record *that this concept **is** that concept, imported*, nor **what tier it held there**. Pointing `sources[].resource` at the upstream concept loses precisely the part that matters.
## Proposal
An optional `imported` key that attributes a **foreign** verification rather than asserting a local one, mirroring `verified`'s actor/timestamp shape:
```yaml
imported:
- from: https://example.com/acme/platform-graph # the upstream bundle
at: 2026-09-01T12:00:00Z # when this consumer imported it
concept: concepts/services/checkout.md # optional: the upstream path/id
verified: # the tier AS OBSERVED upstream, verbatim
- { by: human:alice, at: 2026-08-30T09:00:00Z }
```
**The semantic that makes it useful: an imported tier is reportable, not inherited.**
- A concept carrying `imported` and no local `verified` is **unverified locally**, whatever the upstream said.
- A consumer may display "human-reviewed in `acme/platform-graph`" — which is true, attributable, and checkable — while the emitting bundle claims nothing it did not do.
- A local `verified` may be added alongside, meaning "we imported this *and* confirmed it ourselves". Those are genuinely different states and are currently indistinguishable.
**Transitivity: flatten to one level.** Record the immediate upstream only. A chain would grow without bound, and "A said B said C said" is rarely actionable; the immediate source is who you would go and ask.
## Backwards compatibility
- Optional. Absent means exactly today's behaviour, so every existing bundle stays valid and every existing consumer keeps working.
- Adds no new actor forms — `from` is a resource, and the nested `verified` reuses §7 actors unchanged.
- Derived tiers are unchanged: `imported` never *raises* a local tier, so a consumer that ignores the key computes the same (conservative) answer it does today.
- Composes with #13's proposed `refuted` rather than overlapping it — an imported concept can carry an upstream refutation by the same rule, and by the same "reportable, not inherited" semantic.
**Not asking for a confidence score.** The spec's reasoning against one — subjective, unportable, goes stale — is sound, and this proposal is consistent with it: `imported` records objective, checkable events (who verified what, where, when), not a judgement.
## Background: what we hit
Roteiro maintains a code-knowledge graph whose facts carry a provenance class, and its mapping onto OKF's tiers is why we adopted the format — human-authored prose to human-reviewed, deterministic AST extraction to machine-confirmed, heuristic inference to unverified. That mapping was a rename rather than an invention, which we took as a good sign about the spec.
Reading bundles broke the symmetry. We had to introduce an *out-of-band* external provenance internally, because there is no way to say it in the frontmatter — which means the distinction exists in our graph and **cannot be expressed in the bundle we emit**. Anyone downstream of us loses it, and we did not choose that; the format left no way to keep it.
We would rather express it in OKF than beside it. Happy to prototype against a draft, and to report back on what a reader/writer round-trip actually needs once we have run it on real bundles.
Contributor guide
Research direction
Start by reviewing the existing verification rules in §5.3 and §7, then compare the proposed `imported` key with the current `sources` semantics and #13's `refuted` proposal. Prototype the representation against reader/writer round-trips using the real bundles mentioned from Roteiro; done means the distinction between local and foreign verification remains attributable without changing existing derived tiers.
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
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100