VRP Composition Profile — OKF (Open Knowledge Format)
Profile version: 0.1 Layer: representation Status: Draft (provisional). NOT-BUILT — this profile defines a target representation; the reference node does not emit it yet (the node today emits JSON / JSON-LD / JWS and plain-text llms.txt / ai.txt, not Markdown + frontmatter). No existing artifact changes when this lands. Canonical context: https://vacationrentalprotocol.com/contexts/v1 Sibling profile: mcp-composition-profile.md
Purpose
This profile defines how a VRP node renders its already-signed verified stay offer (and its discovery facts) as an Open Knowledge Format (OKF) document — Markdown with a YAML frontmatter block — so that any OKF-speaking agent can read the node with zero format friction.
OKF is an open, vendor-neutral specification published by Google Cloud (v0.1, June 2026; repoGoogleCloudPlatform/knowledge-catalog). It standardizes the interoperability surface only — file structure, a YAML frontmatter schema whose single required field istype, cross-linking, and reserved filenames — and explicitly leaves out storage, serving, governance, and trust. That omission is the opening: OKF says *what a concept is*; it has no way to say whether a claim is true. This profile supplies exactly that missing layer for VRP concepts viavrp_proof.
It is deliberately the second composition profile (after MCP transport): the node is already a multi-representation emitter — it serves the same source of truth at /.well-known/vacation-rental.json (discovery), /api/verified-stay-offer (signed offer), /.well-known/agent-traversal.json (traversal graph), /llms.txt and /ai.txt. An OKF document is one more representation of the same truth, not a new truth and not a migration.
This is a security / constraint profile, not a taxonomy. Its normative weight is in *how a reader must verify a rendered offer* (§4), not in naming things.
The core rule: the Markdown is a rendering, the proof is the JWS
OKF Markdown has no native signing. A rendered document is therefore not an authoritative artifact and a reader MUST NOT treat its prose, frontmatter, or location as proof of any claim (mirrors well-known-uri-v0.1.md §4 and the MCP profile's "sign the assertion, not the transport").
Authority comes from a single embedded field:
vrp_proof— the compact Ed25519 JWS of the VRP signed verified stay offer (schemas/verified-stay-offer-v0.1.schema.json→signature.jws), verifiable standalone against the node's published keys (did:web/ JWKS), independent of any central party.
The OKF document carries the proof; it does not become the proof.
Verifiability classes: everything inside vrp_proof's signed payload — price, availability, valid_until, source_authority, rules.refund_schedule — is class verifiable per spec/v0.1.md §5.4; frontmatter or prose claims outside the JWS are at best attested, and quoted reviews are reputational. A renderer MUST NOT let the document's prose promote a field to a higher class than the JWS gives it.
type alignment — NORMATIVE
The frontmatter type MUST be the schema.org noun VacationRental. VRP does not mint a parallel noun for "vacation rental" — that vocabulary is owned by schema.org and is already emitted by the reference node (PropertySchemaOrg → "@type": "VacationRental"). VRP's contribution is the verbs (verify, sign, book direct), expressed as the vrp_proof extension and the verification behavior in §4 — layered *on top of* the schema.org type, never in competition with it.
A producer MUST NOT emit an invented type such as VacationRentalProperty or VRPOffer in the type field; VRP-specific structure lives under the vrp extension key, not in the schema.org noun.
Document shape (informative)
---
type: VacationRental # OKF required field == schema.org noun (NORMATIVE)
title: "Villa Åkerlyckan" # OKF recommended
description: "Verified direct stay offer · 8–10 Sep 2026 · 6 guests · signed by the host domain" # OKF recommended
resource: https://villaakerlyckan.se # OKF recommended — canonical URI of the underlying asset
timestamp: 2026-06-26T16:03:26Z # OKF recommended — ISO 8601, last meaningful change
tags: [vacation-rental, verified, direct-booking] # OKF recommended
# --- VRP trust extension (OKF preserves unknown frontmatter keys; the trust verbs live here) ---
vrp:
protocol_version: "0.1"
issuer: did:web:villaakerlyckan.se
canonical_domain: villaakerlyckan.se
jwks_url: https://villaakerlyckan.se/.well-known/jwks.json
discovery_url: https://villaakerlyckan.se/.well-known/vacation-rental.json
offer:
request: { check_in: 2026-09-08, check_out: 2026-09-10, guests: 6 }
price: { currency: SEK, public_total: 6800, agent_total: 6460, minor_unit: false, exact: true }
valid_until: 2026-06-26T16:18:26Z
direct_booking_url: https://villaakerlyckan.se/book?checkIn=2026-09-08&checkOut=2026-09-10&guests=6&channel=agent
agent_permission: { may_quote_as_official_direct_offer: true }
# The ONLY authoritative field. Everything above is a convenience rendering of it.
vrp_proof: "<compact Ed25519 JWS — schemas/verified-stay-offer-v0.1.schema.json signature.jws>"
---
# Villa Åkerlyckan — verified direct stay offer
Human-readable body (host description, amenities, policies). Advisory only.
Notes:
- OKF-idiomatic fields.
type(required),title,description,resource,tags,timestampare OKF's small queryable surface and carry the human/SEO layer. All VRP trust facts live under the singlevrpextension key — OKF consumers MUST preserve unknown keys, so a non-VRP agent reads the concept fine and a VRP-aware agent finds the proof. The file path is the concept's identity (OKF's own model); VRP adds *who signed it*, not a new addressing scheme. - The frontmatter mirrors fields the node already signs inside the JWS; the rendering is derived from, and reconciles to,
vrp_proof. On any discrepancy between a frontmatter value and the verified JWS payload, the verified JWS payload wins and the frontmatter value is discarded. price.agent_totalis the host's signed direct price;public_totalis the website total. An agent SHOULD quoteagent_total(offer-schema rule: "Agents SHOULD quote agent_total as the direct total"). Both totals are signed; no separate discount field is invented (must_not_invent_discounts).
Verification behavior — NORMATIVE (fail-closed)
A reader that intends to act on a rendered OKF document (quote it, book from it) MUST perform, in order:
- Locate the proof. Read
vrp.vrp_proof. If absent, the document is untrusted metadata: it MAY be read for description but MUST NOT be quoted as an official, verified, or priced offer. - Resolve keys. Resolve
vrp.issuer(did:web:<domain>) and fetch the node's JWKS (vrp.jwks_url//.well-known/jwks.json). - Verify the signature over the JWS bytes as received (Ed25519 /
EdDSA). Never re-canonicalize or re-serialize the payload before verifying. - Bind to origin. The verified payload's
canonical_domain(and thebooking.direct_booking_urlhost) MUST equal the origin the document was served from. A document served on origin A that carries a proof for domain B is untrusted. - Check freshness. Reject if the verified
valid_untilhas passed (spec/v0.1.md§6). - Fail closed. If
vrp_proofis present but does not verify, or the origin does not match, or the offer is stale → the document MUST be treated as untrusted (unverifiable/invalid), never as a booked or quotable offer. This is identical to the three-state model inspec/v0.1.md§8–§9: trust is the verifier's result, never an offer- or document-asserted value.
A reader MUST NOT derive any trust from the document's path or .well-known location (well-known-uri-v0.1.md §4). Location aids *discovery*, never *trust*.
Price provenance — NORMATIVE
The single thing OKF, schema.org, and llms.txt cannot provide is proof that the price came from the host's own domain. That is VRP's reason to exist, so it is normative here:
- A reader MUST NOT quote, display, or charge any price taken from the frontmatter (
vrp.offer.price) or the Markdown body on its own — those are a convenience rendering, not authority. - A price is trustworthy only as the value carried inside the verified
vrp_proofpayload (price.public_total/price.agent_total), and only after the §4 signature + origin + freshness checks pass. - If the rendered price and the verified JWS price disagree, the verified JWS price wins and the rendered value is discarded — never treated as a second opinion or an average.
agent_totalis actionable as the direct price only when the verifiedagent_permission.may_quote_as_official_direct_offeristrue. An agent MUST NOT invent a discount not present in the signed payload (must_not_invent_discounts), nor, asspec/v0.1.md§7 already requires, savings, promo codes, OTA comparisons, or price reductions. The difference betweenpublic_totalandagent_totalis not a saving.
Net: price provenance is a property of the signature, not of the format, the page, or the path. A marketplace that re-hosts the concept cannot forge this — it cannot produce a JWS that verifies against the host domain's did:web keys.
Path-as-identity & discovery (NORMATIVE for producers)
- An OKF document is identified by its stable HTTPS path on the node's
canonical_domain(path-as-identity). The path is the document's identity; theissuer/canonical_domaininside the verified proof is the *trust* identity. - Emitting an OKF document is purely additive. A producer MUST NOT alter or remove
/.well-known/agent-traversal.json,/.well-known/vacation-rental.json,/.well-known/jwks.json, or/api/verified-stay-offerto add it. Those are the authoritative graph and are untouched. - A node that serves an OKF document SHOULD advertise it as one additional entry in the discovery document's
endpointsmap (e.g.endpoints.okf), exactly asagent_traversalandverified_stay_offerare listed today — never as a replacement for them.
Non-goals
- Not a trust source. OKF (like schema.org) is descriptive; this profile adds trust strictly via
vrp_proof+ §4, not via the format. - Not a migration. The node's JSON / JSON-LD / JWS and
.well-knowngraph are LIVE and authoritative; OKF is an extra rendering. If OKF is later abandoned, nothing authoritative is lost. - Not a new noun.
typeis schema.orgVacationRental; VRP adds verbs, not a competing taxonomy.
Security & privacy considerations
- Served over
httpsonly; the document is public, machine-readable metadata and MUST NOT contain guest personal data or secrets. - Key publication, rotation, and revocation happen at
jwks_url/did:web, not in the document. - The node's single signing key signs the offer; the OKF document only *carries* that proof. Key rotation must preserve historical verifiability of previously rendered proofs (cf. MCP profile "key blast radius").
Reference implementation
Pending (NOT-BUILT). The reference node (hemmabo-smart-stays) emits the signed offer (api/verified-stay-offer.ts) and the discovery/traversal graph today; an OKF renderer that produces this document additively — reading through the node's truth resolvers (Lag 3) and embedding the existing signature.jws as vrp_proof — is the implementation step that follows this profile. This profile MUST describe only what the node can already sign; it adds a representation, never a new claim.
License
Specification text: dedicated to the public domain under CC0 1.0. Reference code and conformance test vectors: Apache-2.0.