Documentation · Markdown source · Edit on GitHub · CC0 1.0

Draft: OKF trust-extension proposal (ready to post to GoogleCloudPlatform/knowledge-catalog)

Status: Draft — not yet posted. This is the text to open as a GitHub issue (or discussion) on the OKF repo when we decide to plant the flag. It positions VRP as the trust/verifiability layer OKF deliberately left out — for *all* OKF concept types, not just vacation rentals.

Why this matters for VRP (internal note, do not paste): as of 2026-06-26 the vrp-spec repo had 0 forks / 1 star / 0 issues, and a second, independent implementation — the condition for 1.0 in GOVERNANCE.md §5 — was still open. There is no inbound partner interest yet. OKF is Google's distribution surface for agent-readable knowledge; getting a proof convention in front of that ecosystem is a cheap way to reach the very builders who could become implementer #2 — it does not depend on HemmaBo signing nodes first.


Issue title

Proposal: an opt-in proof extension convention for verifiable OKF concepts

Body (paste from here)

Summary

OKF v0.1 standardizes how a concept is *described* (markdown + YAML frontmatter, required type, consumers preserve unknown keys) but is explicit that trust, governance, and serving are out of scope. For a growing class of concepts — priced offers, datasets, metrics, API contracts — a consuming agent needs to know not just *what the concept says* but *whether it provably came from the claimed source*. OKF has no convention for that today.

This proposes a minimal, opt-in, schema-free convention (not a spec change): a reserved-by-convention proof frontmatter key carrying a detached signature, so that any producer can make a concept *verifiable* and any consumer can fail closed on an invalid one — while non-verifying consumers ignore it exactly as OKF already requires for unknown keys.

Non-goals (kept faithful to OKF's minimalism)

Proposed convention

---
type: VacationRental
title: "Example property"
resource: https://example.com
proof:
  alg: EdDSA                       # signature algorithm
  kid: <key id>                    # key identifier in the producer's key set
  keys: https://example.com/.well-known/jwks.json   # how to resolve verification keys
  issuer: did:web:example.com      # who is asserting this concept
  sig: <compact JWS over the concept's signed payload>
---

Consumer rules (fail-closed)

  1. If proof is absent → treat the concept as descriptive only (today's behavior; unchanged).
  2. If proof is present, a consumer that intends to *act* on the concept MUST: resolve issuer/keys, verify sig over the signed payload, and confirm the issuer/origin matches where the concept was served.
  3. If proof is present but does not verify (bad signature, origin mismatch, expired) → the concept MUST be treated as untrusted, never as verified.
  4. Trust is the verifier's result — never asserted by the document, the type, or the file path.

Reference implementation

The Vacation Rental Protocol (https://vacationrentalprotocol.com, spec under CC0) is a working instance of exactly this pattern for type: VacationRental concepts: a host domain serves a signed offer, and an agent verifies the price and availability came from that domain before quoting or booking — 0% intermediary. Live: curl https://villaakerlyckan.se/.well-known/vacation-rental.json. VRP's profile mapping OKF ↔ proof is published at spec/profiles/okf-profile-v0.1.md in vacationrentalprotocol/vrp-spec.

We are offering this as a generalizable convention because the trust gap is not specific to rentals — any priced or sourced OKF concept has it.

Question for maintainers

Would the OKF project accept (a) a documented proof convention in the spec's "extension keys" guidance, or (b) at minimum a link from OKF docs to independent trust profiles like VRP that demonstrate it? Happy to open a PR for whichever shape fits OKF's minimalism.