GoogleCloudPlatform / GoogleCloudPlatform/open-knowledge-format

Proposal: `imported` — attribute a concept taken from another bundle without inheriting its trust

Open
#15 1 comment 0 reactions 0 assignees View on GitHub
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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.