GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
feature[trust]: optional field on a verification event called `revision`
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
OKF v2 section [5.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md#52-trust-generated-and-verified) defines a verification event as `{ by, at }` meaning an actor confirmed the content "against its sources or `resource`" at some instant.
```
verified: { by: human:ahormati, at: 2026-06-25T09:00:00Z }
```
The next logical iteration is to record what the source looked like then.
- when the `resource` is a folder path inside a versioned bundle, the git commit that recorded the event pins it (by luck of external dependency, breaks outside git world).
- when the `resource` is a URL, is not recorded either way. A page that changes after `human` confirmed has not trace, so a reader (verifier, auditor, detective, human or otherwise) cannot tell if **human-reviewed** (section 5.3, the trust story) still applies to the page.
- Section 5.1 (Provenance: sources) offers `sources[].last_modified` records when the source changed as the producer knew it, but not what the verifier saw (unless producer refreshes after every change). Producer could add a new key to capture a `version` in the verification event but that field has unknown meaning in OKF v2 - so introducing the key will enhance the core credibility/trust tiers story imho.
**Proposal**
In **Versioning (section 12)**,
An optional field on a verification event called `revision` and an appropriate narrative that follows the OKF style.
```yaml
verified:
- by: human:ahormati
at: 2026-06-25T09:00:00Z
revision: "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c
```
- `revision`: its Optional. The version of the checked `resource`: a commit id, an ETag (rfc-9110) or version label, or a content digest of the resource as retrieved (`:`). Absent means unrecorded, never "unchanged".
- Several `sources` neeed one pin each: a `checked: [{ resource, revision }]` list on the event, with bare `revision` as the shorthand for a single `resource`,
- The same field on `generated` says which version the content was generated from.
So consumer could then say "_human-reviewed, against revision X_", and a refresh can tell "the source moved since the last human check" from "nobody looked".
Contributor guide
Research direction
Read okf/SPEC.md sections 5.1, 5.2, 5.3, and 12 to understand the existing provenance, trust, and versioning language. Compare the proposed verification and generated-event forms, including the single-resource shorthand and multiple-source `checked` list. Done means the specification clearly defines the optional `revision` field and its relationship to resources, source pins, commit IDs, ETags, and content digests.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- git
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100