GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

feature[trust]: optional field on a verification event called `revision`

Open
#437 0 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 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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.