Vacation Rental Protocol - Specification v0.1
Status: Public draft Published: 2026-05-20 Canonical URL: https://vacationrentalprotocol.com Repository: https://github.com/vacationrentalprotocol/vrp-spec
1. Scope
Vacation Rental Protocol (VRP) v0.1 defines how a host-owned vacation rental domain publishes discovery metadata, signing keys, and signed verified stay offers so AI agents can verify provenance, freshness, exact price, and direct booking URL.
VRP v0.1 is not an OTA, marketplace, central registry, public traffic proxy, payment processor, or central key issuer.
VRP v0.1 is a no-gatekeeper protocol. Verification MUST NOT require HemmaBo, a VRP-operated trusted issuer registry, a host accreditation program, a certification company, or a central discovery index.
VRP may compose with adjacent agent-commerce standards. UCP can handle checkout and order lifecycle, including lodging flows as the UCP lodging profile matures; AP2 can handle payment mandates; a future agent-native settlement rail (e.g. x402) is reserved but not defined (see §5.2); MCP can expose future tool bindings; and A2A can carry future agent-to-agent negotiation. VRP v0.1 does not define those runtime flows.
1.1 Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 (RFC 2119, RFC 8174) when, and only when, they appear in all capitals, as shown here.
2. Discovery Document
A VRP host domain publishes:
https://{host-domain}/.well-known/vacation-rental.json
Required fields:
protocol: MUST bevacation-rental-protocol.protocol_version: MUST be0.1.canonical_domain: MUST match the host-owned domain being verified, which is the domain this document is fetched from.jwks_url: MUST point to the host-domain JWKS, and MUST be a node URL (below).verified_stay_offer_endpoint: MUST point to the host-domain verified stay offer endpoint, and MUST be a node URL (below).
Host-owned domain. A VRP node is a domain registered for the host, never a name under another party's domain. canonical_domain MUST meet all of the following:
- It is lowercase ASCII, with internationalized labels in A-label (
xn--) form, and has no trailing dot. - It equals its own registrable domain as computed by the Public Suffix List algorithm using only the rules in the list's ICANN section, each rule compared in A-label form; where no ICANN rule matches, the algorithm's default rule
*applies. The list's PRIVATE section does not count: it lists domains under which a company hands out names to its customers. - Its top-level domain is not a brand or closed top-level domain, under which every name belongs to the top-level domain's operator. These are: Specification 13, marked
"specification13": truein ICANN's gTLD list (https://www.icann.org/resources/registries/gtlds/v2/gtlds.json); and list changes only by ADR.- every top-level domain whose ICANN registry agreement includes
bookingandhotels, whose registry operator is Booking.com B.V. This
A name under a platform, catalog, marketplace, OTA, site builder or operator domain is never a canonical_domain, whoever operates that domain. example.com and example.co.uk are host-owned domains; www.example.com, villa.platform.example, villa.booking and villa.amazon are not. A verifier that holds no copy of the ICANN section of the Public Suffix List, or of ICANN's gTLD list, MUST treat the node as unknown (§9).
Node URL. A node URL is an absolute https URL whose host is canonical_domain or www. followed by canonical_domain, with no userinfo (no user name or password) and no port other than the https default. Hosts are compared after URL parsing, which lowercases them.
Fetching. The domain a discovery document, a JWKS or an offer is fetched from is the host of the URL the verifier requested. A verifier requests the discovery document at https://{domain}/.well-known/vacation-rental.json for the domain it is verifying, which the document's canonical_domain then has to match. A verifier MAY follow a redirect only when its target is a node URL of that domain; it MUST NOT follow any other redirect, and MUST treat what it would have fetched as unknown (§9).
Conformance vectors for these rules, §5.1 and §7: examples/conformance/host-domain/.
Recommended fields:
node_idcapabilitiesoperator— MAY carryname,role, andkey_custody.key_custodydeclares who holds the node's Ed25519 signing key:platform(an operator holds and operates the key on the host's behalf — offers are signed under the host's domain identity and remain independently verifiable againstjwks_url, but the host does not hold the key itself) orself(the host self-custodies their own key). Absent = unspecified; a verifier MUST NOT assume self-custody. This lets an agent reason about exactly what a valid signature guarantees — provenance and integrity in both cases, host self-sovereignty only whenself.endpoints
2.1 Node page identification
A VRP node is found and verified through its discovery document (§2) and its signed offers (§5). The pages a guest or an AI model reads are not part of that chain, so nothing in v0.1 has required them to name the protocol. The rules below make the protocol visible there too. In v0.1 they are SHOULD; ADR 0006 records that (a) and (b) are intended to become MUST in the next MAJOR version, the migration path being these two tags.
For the page served at https://{canonical_domain}/:
- (a) The document head SHOULD contain
<link rel="protocol" href="https://vacationrentalprotocol.com/">. - (b) The document body SHOULD contain a visible hyperlink carrying
rel="protocol"whosehrefis on the originhttps://vacationrentalprotocol.com— the root, or/verify?host={canonical_domain}— and whose link text contains the stringVRP. - (c) The response SHOULD carry the HTTP header
Link: https://vacationrentalprotocol.com/; rel="https://vacationrentalprotocol.com/rel/protocol". - (d) schema.org JSON-LD on the page SHOULD mark the lodging with
"additionalType": "https://vacationrentalprotocol.com/terms#VRPVacationRental". - (e) The page SHOULD describe the property as a VRP vacation rental in its own language (for example «VRP-semesterboende»).
The href in (a) and (b) MUST NOT point to an implementation, an operator, or any origin other than https://vacationrentalprotocol.com: the link names the standard, never a vendor. The HTML keyword protocol and the extension relation type https://vacationrentalprotocol.com/rel/protocol denote the same relation; see /rel/protocol. (a) and (b) are checked by scripts/verify-node-page.mjs against the vectors in examples/conformance/node-page/; (c)–(e) are reported, not enforced. *Visible* in (b) means rendered visible to a reader. The checker does not render a page: it tests the link's own attributes (hidden, aria-hidden="true", an inline display: none). A link hidden by an ancestor element or by a stylesheet passes the checker and still fails (b); the checker is necessary, not sufficient.
3. JWKS
A VRP host domain publishes an Ed25519 public key set:
https://{host-domain}/.well-known/jwks.json
Keys used for signing verified stay offers MUST use:
kty:OKPcrv:Ed25519alg:EdDSAkid: stable key identifierx: base64url Ed25519 public key
Such keys SHOULD also set:
use:sigkey_ops: includeverify
The JWKS structure is pinned by schemas/jwks-v0.1.schema.json.
3.1 Key Rotation and Revocation
A node's signing authority is the Ed25519 key set published at its jwks.json (and mirrored by did:web). Because there is no central issuer, the JWKS is the only revocation authority: a key is valid exactly while it appears in the node's JWKS.
Rotation. To rotate, a node MUST publish the new key alongside the old one in its JWKS and sign new offers with the new key's kid. It SHOULD retain the old key in the JWKS until every offer signed with it has passed its valid_until, so the retention overlap equals the maximum offer lifetime (900 seconds, §5). A node SHOULD use a kid that encodes a date and sequence (e.g. example.com-2026-05-18-01) so operators can order keys; a verifier MUST treat kid as opaque and MUST NOT infer trust, recency, or status from its value.
Refresh on miss. If a verifier receives an offer whose kid is not present in its cached JWKS, it MUST re-fetch the node's JWKS before acting, and only treat the offer as unverifiable if the kid is still absent. This makes a rotation take effect immediately (the new key is picked up on first use) and decouples rotation from the cache bound below, so the cache bound governs revocation latency alone. To avoid amplification, a verifier SHOULD rate-limit or coalesce refresh-on-miss per domain, so a stream of offers bearing unknown kids cannot drive it into excessive JWKS fetches against the node.
Revocation. A key's *presence in the JWKS is the entire trust signal*: an offer verifies only against a key that is in the JWKS now. Removing a key therefore makes every offer signed with it unverifiable, regardless of when it was signed — there is no retroactive "historically valid" exemption (and a conforming verifier could not honor one anyway, since it only knows whether a key is currently present).
- *Routine rotation* avoids breakage through timing: retain the outgoing key until its outstanding offers have passed
valid_until, then remove it — no live offer is still signed by it, so nothing breaks. - *Compromise* requires immediate removal. This also invalidates the operator's own legitimate offers signed with that key — that is intentional: a verifier cannot distinguish the operator's offers from an attacker's, because they share the same key and produce equally valid signatures. Re-sign legitimate stays with the new key.
Offer freshness (valid_until, §6) does NOT bound a compromise — an attacker holding the leaked private key can mint fresh offers with a future valid_until that pass the freshness check. The only thing that stops a conforming verifier from honoring them is the key being absent from the JWKS it holds. Therefore:
- A verifier MUST NOT cache a node's JWKS for longer than 5 minutes. A node's
Cache-Controlmay only *shorten* this window, never extend it — the 5-minute cap is absolute. This bound is the revocation latency: a compromised key is fully de-trusted by conforming verifiers within the cache window after it is removed from the JWKS. - A node SHOULD serve
jwks.jsonwith a shortCache-Control(e.g.max-age=300or less). The JWKS is a small, CDN-cacheable document, so frequent re-fetching is inexpensive.
Three distinct controls (do not conflate). Freshness (valid_until, §6) bounds how long an offer is quotable; refresh-on-miss gives immediate discovery of the current key set (rotation); the JWKS cache cap bounds how long a revoked key is still accepted (revocation latency). They are independent — none substitutes for another.
Threat model. The root of trust is domain control (did:web): the key set is whatever the host domain serves. Rotation and revocation protect the case where a *signing key* leaks while the *domain remains under the operator's control*. They do NOT protect against compromise of the domain itself — an attacker who can serve the domain's jwks.json can publish their own keys, and no key-level mechanism can detect that. Domain-level security (DNS, TLS, hosting) is out of scope for VRP and is the operator's responsibility.
Enforcement honesty. VRP cannot *force* a verifier to cache for a bounded time. The cache bound is a MUST on *conforming* verifiers; there is no protocol backstop against a non-conforming verifier that caches a revoked key indefinitely. Treat the bound as a conformance requirement, not a guarantee VRP can enforce.
Optional transparency-log composition. A node MAY record key-rotation events (key added / key removed, with kid and timestamp) in its append-only transparency log (see transparency-log-v0.1), giving a tamper-evident history of which keys were valid when — useful for after-the-fact disputes about whether an offer was signed by a then-valid key.
4. Verified Stay Offer Endpoint
The verified stay offer endpoint accepts at least:
check_in: arrival date inYYYY-MM-DDcheck_out: departure date inYYYY-MM-DDguests: integer guest count
The endpoint returns a signed verified stay offer envelope. The signed payload contains the quoteable facts.
5. Signed Offer
The signature format is compact JWS using EdDSA over an Ed25519 key published in the host-domain JWKS.
The signed payload MUST include:
kind:verified_stay_offerprotocol_version:0.1canonical_domainnode_idgenerated_atvalid_untilrequestpropertyavailabilitypricebookingagent_permission
The stay asked for. request is the stay the offer is for, as it was asked for at the offer endpoint (§4): check_in and check_out are dates in YYYY-MM-DD form, and guests is an integer of at least 1.
check_inandcheck_outMUST be dates that exist in the calendar (RFC 3339full-date), andcheck_outMUST be later thancheck_in.- A node MUST NOT sign an offer for dates that break these rules, or whose
check_inis earlier than the current date at the property. It answers with an error instead. check_in,check_out,guestsandlanguageare the requester's words, echoed back; they are not statements by the host.check_in_weekday,check_out_weekdayandnights, when present, are the node's own, computed from the two dates. A node MUST NOT copy into the signed payload any value from the request other than those four.request.language, when present, MUST be a BCP 47 language tag made of a language subtag (two or three letters), optionally a script subtag (four letters) and optionally a region subtag (two letters or three digits), joined by hyphens; letter case does not matter, as in BCP 47. It SHOULD name a language the node writes the offer in.
Lifetime. generated_at and valid_until are UTC date-times in the form the schema pins (RFC 3339 date-time, ending in Z). A node MUST set generated_at to the time it signs the offer. valid_until MUST be later than generated_at and MUST NOT be more than 900 seconds (15 minutes) after it. The two values are compared as written, fractions of a second included.
Conformance vectors for the stay asked for, the dates, the language tag and the lifetime (§5, §6, §7): examples/conformance/offer-rules/.
The signed payload MAY also include host-verified direct-source facts, so an agent can verify (not just read) the node's positioning:
source_authority—model: host_verified_direct_source,is_official_source_for_property,intermediary: none,payment_recipient: host,booking_model: direct_with_host,booking_commission_pct: 0. A reselling marketplace cannot sign these.price.no_add_on_fees—trueasserts the quoted total has no add-on booking, service, or cleaning fees (the displayed price is the total paid). This is the node's own fee structure, never an OTA comparison.price.minor_unit— the unit of every amount inprice(public_total,agent_total,total, eachbreakdown[].nightly_rate, eachadjustments[].amount, thereconciliationsums).true: integers in the currency's minor unit (cents, öre):29100is 291.00 EUR.false: whole currency units:8930is 8 930 SEK. The schema requires the flag, and it applies to the wholepriceobject; a consumer reads it before it quotes, converts or displays an amount.
The envelope and payload structure is pinned by schemas/verified-stay-offer-v0.1.schema.json, which is authoritative for v0.1 offer shape. A real, verifiable Ed25519/JWS example and its failure modes are in examples/conformance/.
5.1 Direct Booking URL
The signed payload booking object carries the direct booking URL the agent routes the user to. The booking object MUST include:
direct_booking_url
direct_booking_url is the only booking action a VRP agent may take for the offer (see §7). The following rules define its structure, integrity, and lifecycle.
Structure.
direct_booking_urlMUST be an absolutehttpsURL.- It MUST be a node URL (§2) of the offer's
canonical_domain: its host is the offer'scanonical_domainorwww.followed by it, and no other name, with no userinfo and no port other than thehttpsdefault. It MUST NOT point at any other host: another name under the node's domain, another node's domain, a name under a platform, catalog, marketplace or operator domain, an OTA, a link shortener or a redirector. An agent that cannot confirm that it is a node URL MUST treat the direct booking URL asunknown(see §9) and MUST NOT route booking to it. - The URL SHOULD encode the quoted stay so that the booking page opens pre-filled for the same stay the agent quoted. The RECOMMENDED query parameters are:
checkIn: arrival date asYYYY-MM-DD, matching the offerrequest.check_in.checkOut: departure date asYYYY-MM-DD, matching the offerrequest.check_out.guests: integer guest count, matching the offerrequest.guests.
- The URL MAY include an offer reference identifier (for example an
offerquery parameter) so the host node can correlate the click with the signed offer it issued. The reference identifier, when present, MUST NOT be required by a verifier to validate the offer, and MUST NOT be treated as a substitute for verifying the JWS signature. - The URL MAY include additional host-specific query parameters. A verifier MUST ignore unrecognized query parameters and MUST NOT treat their presence as a verification failure.
Integrity. direct_booking_url is a field inside the signed offer payload. Its integrity derives solely from the compact JWS over that payload (§5): if the JWS verifies against the host-domain JWKS, the direct booking URL is exactly the URL the host signed. There is no separate signature over the URL, and an agent MUST NOT accept a direct_booking_url delivered outside, or modified after, the signed payload. A direct_booking_url whose enclosing offer fails signature verification is unknown and MUST NOT be used.
Lifecycle. The direct booking URL is actionable only while the enclosing offer is fresh, that is while valid_until holds (§6).
- While the offer is fresh, an agent MAY present and route the user to
direct_booking_urlsubject to the Safe-to-Quote rules (§7). - Once
valid_untilhas passed, the offer is stale. The agent MUST treat the direct booking URL asunknownand MUST NOT present its associated price as current or claim the stay is bookable on the strength of the stale offer. The agent SHOULD fetch a fresh signed offer for the user's dates and guest count (§6) before routing a booking action. - After expiry, the host node MAY continue to serve the same URL, MAY re-quote (return a new signed offer, which may carry a different price, availability, or
direct_booking_url), or MAY return an unavailable or non-quoteable offer. Following an expireddirect_booking_urlis therefore an unverified action: the host, not the protocol, decides what the URL does after expiry. - A host node SHOULD ensure that following
direct_booking_urlafter expiry fails closed for the guest — for example by re-quoting on the landing page rather than silently honoring a stale price. VRP does not guarantee that a price observed in an expired offer is still available.
The booking object shape is pinned by schemas/verified-stay-offer-v0.1.schema.json. The schema validates that direct_booking_url is present and is an https URL; the canonical_domain host constraint and the query-parameter recommendations above are normative protocol rules that a verifier enforces at runtime, not structural schema constraints.
5.2 Reserved: optional agent-native payment rails
VRP v0.1 defines exactly ONE payment path: direct_booking_url (§5.1), settled by the host's own processor (fiat, e.g. Stripe). This is deliberate — every field VRP defines is one a live node actually honors and an agent can verify.
The optional booking.payment_options[] field is RESERVED for a future agent-native payment-rail binding (e.g. x402) and is NOT defined in v0.1: its shape, settlement, refund handling, and reconciliation are intentionally left open. A node SHOULD omit it and rely on direct_booking_url; an agent MUST NOT treat its presence as a defined, honorable payment path.
Why reserved, not specified: agent-native rails are a moving target (x402 added sessions in a later revision; competing models such as ACP, AP2, and session-based protocols are unsettled; refund and chargeback semantics for real bookings are unsolved), and Stripe already ships x402 — so the concrete binding will likely arrive largely for free once non-US stablecoin receipt opens for the host's own account. Specifying the mechanics now would publish a field no live node honors — the "coming soon" vapor VRP exists to replace — and risk locking a shape the moving target will break. The name is reserved so the slot cannot be squatted with a conflicting meaning; the binding is hand-specified later, when a winning rail and a non-US settlement path exist.
Two invariants WILL hold whenever the binding is defined, and constrain it now: the payee is the host's own (never an intermediary, OTA, or HemmaBo), and rails MUST NOT gate discovery, verification, or offer retrieval (no-gatekeeper, §1).
5.3 Computable refund schedule (optional)
A node MAY publish its cancellation refund terms inside the signed offer as rules.refund_schedule — an array of rows { "hours_before_checkin": int ≥ 0, "refund_percent": int 0–100 }.
The schedule is computable, not descriptive: an agent (or a future agent-native settlement rail, §5.2) evaluates it as a pure predicate with no platform context:
- Compute
H = floor((check-in moment − cancellation time) / 1 hour)— whole hours, floored. Flooring makes fractional boundaries resolve in the node's favour; implementations MUST NOT substitute other rounding. - Sort rows by
hours_before_checkindescending. The FIRST row withhours_before_checkin ≤ Happlies; the guest receives that row'srefund_percentof the paid total. - No matching row — including any cancellation after the check-in moment, where
His negative — means 0 %.
A row with hours_before_checkin: 0 therefore means "this percent up to the check-in moment itself". An EMPTY array is a valid, honest schedule meaning "no refund at any point". An ABSENT or null field means the node has not published computable terms: the answer is unknown, and an agent MUST NOT invent, infer, or default a refund promise.
Because the schedule is signed inside the offer (§5) it is verifiable, not merely attested: the guest's agent can prove after the fact exactly which refund terms were in force at quote time, regardless of what the node's pages say later. Nodes and agents MUST relay the rows verbatim to guests — as hours/percent terms, never re-labelled into named tiers ("flexible", "moderate", …), which this field replaces.
5.4 Verifiability classes
VRP data falls into exactly three classes. When an agent (or a human) asks "how do I know this?", the answer is one of these — and a surface MUST NOT present a lower class as a higher one (an attested amenity is never "verified"; a review aggregate is never a term of the booking).
- verifiable — fields signed INSIDE the offer's compact Ed25519 JWS (§5) and, where the node emits receipts, bound byte-for-byte into the same receipt attestation and transparency-log leaf. One signature, one log entry, one timestamp: price (including
exactandno_add_on_fees),availability,valid_until,source_authority, andrules.refund_schedule(§5.3). Tampering with any of them kills the same signature; a guest's agent can prove after the fact exactly which terms were in force at quote time.refund_scheduleis the canonical example of a field deliberately MOVED into this class: cancellation terms used to be presentation-layer tier labels (attested at best), and are now signed rows inseparable from the price they govern.
- attested — host-declared tri-state claims (amenities, policies) published in the node's discovery document and optionally as a
VRPPropertyAttestedClaimsCredential(attestations-v0.1.md §5.5). Actionable as the host's explicit statement — including negations ("cats are not allowed") — but not cryptographically bound to a specific purchase moment. Absence is Unknown, never a yes or a no.
- reputational — review aggregates, stay history, and similar evidence about past experience. An agent MAY cite it (accurately attributed and time-bounded) but MUST NOT present it as a promise, a term, or a fact about the current offer.
Determining the class of a field is mechanical, never editorial: the class follows from WHERE the value was read, not from how any surface phrases it. Read from inside the offer JWS payload (after signature verification) → verifiable. Read from the discovery document's claims or an attestation credential → attested. Read from review data → reputational. A value that appears in more than one place carries the class of the surface it was actually read from — reading an amenity from the discovery document never inherits the offer's signature, even when the same value also happens to appear inside a signed offer. If a host asserts something OUTSIDE the signed payload — in prose, frontmatter, marketing copy, or an unsigned field — a renderer MUST treat it as attested at best, regardless of wording: language like "verified", "guaranteed", or "signed" attached to an unsigned value is a class violation, not a promotion.
6. Freshness
Agents MUST treat an offer as non-quoteable if valid_until is missing, malformed, or expired.
Agents MUST also treat an offer as non-quoteable if generated_at is missing or malformed, if generated_at is more than 60 seconds later than the agent's current time, or if valid_until is not later than generated_at or is more than 900 seconds after it (§5). The 60 seconds allow for clocks that are not exactly in step; they do not lengthen the lifetime.
Agents SHOULD fetch a fresh offer for the user's specific dates and guest count before presenting a final price or booking URL.
7. Safe-to-Quote Rules
An agent MUST NOT quote an offer as an official host-domain verified offer unless all of the following are true:
- The discovery document is fetched from the host-owned domain (§2), and its
canonical_domainis that domain. - The discovery document declares
protocol: "vacation-rental-protocol". - The discovery document declares
protocol_version: "0.1". - The JWKS contains an Ed25519 verification key matching the JWS.
- The compact JWS verifies against the host-domain JWKS.
- The signed payload matches the returned offer.
- The signed payload's
canonical_domainis the domain the discovery document was fetched from. valid_untilis present and fresh.generated_atandvalid_untilmeet §5 and §6:valid_untilis later thangenerated_atand at most 900 seconds after it, andgenerated_atis not more than 60 seconds later than the agent's current time.request.check_inandrequest.check_outare dates that exist,request.check_outis later thanrequest.check_in, andrequest.check_inis not earlier than the day before the agent's current date in UTC. The local date anywhere is at most one day behind the UTC date, so acheck_inearlier than that has passed everywhere; the node itself applies the property's own date (§5).request.check_in,request.check_outandrequest.guestsare the dates and the guest count the agent asked for.request.language, when present, has the form §5 gives.availability.availableis true.price.exactis true.- A direct booking URL is present.
agent_permission.may_quote_as_official_direct_offeris true.
When safe, the canonical phrase is:
I found the official host-domain verified offer for this stay.
Agents MUST NOT:
- Invent discounts, savings, promo codes, OTA comparisons, or price reductions.
- Say the stay is bookable unless
availability.availableis true and agent permission allows quoting. - Quote a final total unless
price.exactis true in the signed offer. - Route booking action anywhere except the signed direct booking URL.
- Present a value from
requestas something the host stated (§5).
8. Fail-Closed Behavior
Agents and clients MUST fail closed. If signature verification, the offer's binding to the fetched domain and to the stay asked for (§7), freshness and lifetime (§5, §6), the dates (§5), exact price, availability, direct booking URL, or citation permission cannot be verified, the offer MUST NOT be quoted as official or bookable.
9. Three-State Verification
Agents and clients interacting with VRP nodes MUST distinguish three states for any required endpoint or field:
- Affirmed: present, signed where required, fresh, schema-valid, and explicitly true or present. May be cited.
- Negated: present, signed where required, fresh, schema-valid, and explicitly false. May be cited as false.
- Unknown: absent, unsigned, stale, unreachable, schema-invalid, malformed, expired, or otherwise unverifiable. MUST NOT be cited as true or false.
Unreachable is not the same as negated. A timeout, DNS failure, HTTP failure, blocked fetch, invalid JSON, missing field, failed signature check, stale valid_until, or schema mismatch means unknown.
Inference from Unknown to either Affirmed or Negated is a protocol violation. Agents SHOULD tell the user that the value could not be verified and fetch a fresh signed offer before making booking, availability, price, or official-source claims.
Examples: see three-state-verification.md.
10. Core JSON Schemas
VRP v0.1 core artifacts have machine-readable JSON Schemas:
https://vacationrentalprotocol.com/schemas/discovery-v0.1.schema.json
https://vacationrentalprotocol.com/schemas/jwks-v0.1.schema.json
https://vacationrentalprotocol.com/schemas/verified-stay-offer-v0.1.schema.json
https://vacationrentalprotocol.com/schemas/verified-stay-offer-verification-result-v0.1.schema.json
Repository copies are in schemas/. The schemas are interoperability aids for implementers and examples. They do not create a central validator, issuer, registry, certification service, marketplace, OTA, booking intermediary, or trust authority.
11. Portable Attestations
Portable attestations are a document-only extension to VRP v0.1 for privacy-minimized trust history. Core VRP proves that a concrete offer is real; portable attestations prove selected host-domain, payment-path, policy, and optional verified-stay facts without making HemmaBo or any other operator the central issuer, registry, scorer, OTA, marketplace, booking intermediary, or trust authority.
See attestations-v0.1.md.
12. Node Structure Declarations
Node structure declarations are a document-only extension to VRP v0.1 for falsifiable commercial-structure claims. Core VRP proves that a concrete offer is real; structure declarations state what kind of commercial thing the node is — marketplace or not, commission or none, gatekeeper or none — where every claim carries its own verification procedure that any party can execute against the live node, and claims a node can only vouch for itself are strictly separated from claims anyone can verify.
See structure-declarations-v0.1.md.
13. Reference Proof
Villa Åkerlyckan is a live proof node:
villaakerlyckan.se
-> /.well-known/vacation-rental.json
-> /.well-known/jwks.json
-> signed verified_stay_offer
-> direct booking URL
HemmaBo is a reference implementation and provider/federation using VRP. VRP is neutral and implementable by others.
14. Security Considerations
This section is informative. It gathers the security properties and limits that this document states elsewhere; where a rule applies, the section that states it governs, and nothing here adds to or relaxes it.
- The root of trust is domain control. The key set a verifier trusts is whatever the host domain serves at
jwks.json(§3). Rotation and revocation protect against a leaked signing key while the domain stays under the operator's control. They do not protect against compromise of the domain itself: an attacker who can serve the domain'sjwks.jsoncan publish their own keys, and no key-level mechanism can detect that. DNS, TLS and hosting security are the operator's responsibility and out of scope for VRP (§3.1). - What a valid signature proves. A signature that verifies against the host domain's JWKS proves that a key the domain publishes signed exactly these terms (§5): provenance and integrity of the offer. Who holds the private key can be declared per node in
operator.key_custody(§2). Withself, the host holds it. Withplatform, an operator holds and uses it on the host's behalf; the signature then proves that the domain's published key signed, not that the host itself held the key. A verifier does not assume self-custody whenkey_custodyis absent (§2). - Domain binding. A valid signature proves which domain's key signed, not which domain the offer is about. If the node at one domain signs an offer whose
canonical_domainnames another domain, the signature verifies against the signing node's JWKS; only the check that the offer names the domain it was fetched from (§7) stops an agent from presenting it as the other domain's offer. - The stay asked for. A genuine offer for other dates or another guest count verifies like any other offer from the node. Only the comparison with what the agent asked for (§7) stops an agent from quoting it for the wrong stay.
- Echoed request fields. A node signs whatever it copies from the request. If it copied free text, anyone could get a host-signed sentence of their own choosing by asking for it. §5 therefore limits what is copied to the stay and a language tag, and §7 forbids presenting either as the host's words.
- Offer lifetime. A leaked key mints fresh offers whatever the lifetime (§3.1), but an offer the node itself signed stays quotable after a price or availability change for at most its lifetime. §5 caps that at 900 seconds, and the check on
generated_at(§6) keeps a start time in the future from stretching it. - Concentration under platform custody. An operator that holds the signing keys of many nodes is one point of compromise for all of them. Rotation and revocation (§3.1) work per node: removing a compromised key from one node's JWKS de-trusts it for that node, within the cache bound. A key that several nodes publish is de-trusted only where it is removed.
- Key compromise and revocation latency. Offer freshness (
valid_until, §6) does not bound a compromise: whoever holds a leaked key can mint fresh offers. Revocation is removal of the key from the JWKS, and its latency is the verifier's five-minute JWKS cache bound (§3.1). Removing a compromised key also invalidates the operator's own offers signed with it; that is intentional, because the operator's and an attacker's signatures are indistinguishable under the same key (§3.1). - Enforcement honesty. VRP cannot force a verifier to honour the cache bound. It is a conformance requirement on verifiers, not a guarantee the protocol can enforce (§3.1).
- Booking-path integrity. The rules for
direct_booking_url(§5.1) — a node URL of the offer'scanonical_domain(§2), no shortener or redirector, integrity solely from the enclosing JWS, actionable only while the offer is fresh — exist so that a tampered or substituted offer cannot route a guest's booking, and payment, to an attacker. An agent that cannot confirm the host treats the URL as unknown (§5.1, §9). - Host-owned domains. Only a domain registered for the host can be a node (§2). A company that hands out names under its own domain, as the Public Suffix List's PRIVATE section records, cannot make those names VRP nodes, and neither can the operator of a brand or closed top-level domain. ICANN's gTLD list marks brand top-level domains (Specification 13) but not every closed one; §2 therefore names the closed top-level domains it stops beyond that list, and a closed top-level domain that is neither marked nor named is excluded by the rule's wording but not yet by a program.
- Fail-closed verification. Whatever cannot be verified is unknown, never affirmed or negated (§8, §9), so a timeout, a malformed response or a failed signature check cannot be turned into a quote.
- Amplification. §3.1 asks verifiers to rate-limit or coalesce refresh-on-miss per domain, so that a stream of offers bearing unknown
kids cannot be used to drive traffic against a node's JWKS endpoint. - Transport. The discovery document is served over
httpsonly (well-known-uri-v0.1 §5).jwks_url,verified_stay_offer_endpointanddirect_booking_urlare node URLs, sohttpson the node's own domain (§2, §5.1), and a verifier follows a redirect only to a node URL (§2). - Tamper evidence. A node can record signed-artifact hashes and key-rotation events in an append-only transparency log (§3.1; transparency-log-v0.1), giving a tamper-evident, not immutable, history for later disputes about which key was valid when.
Further reading: the threat model (docs/security/THREAT_MODEL.md), key rotation (docs/security/KEY_ROTATION.md) and incident response (docs/security/INCIDENT_RESPONSE.md).
15. Privacy Considerations
This section is informative.
- Public, site-wide metadata. The discovery document and the JWKS describe the site and its keys; they are public and machine-readable. well-known-uri-v0.1 §5 keeps guest personal data and secrets out of the discovery document. The JWKS carries public keys only (§3); this document states no separate rule for it.
- Offers echo the request. A verified stay offer echoes the requested dates and guest count (
request, §4, §5) and is short-lived (at most 900 seconds, §5, §6). None of the fields this document requires identifies a guest. - No verifier identity. This document defines no authentication or verifier identity for fetching the discovery document, the JWKS or an offer (§2–§4), so a node learns no more about the requester than any web server learns from an HTTP request.
- Stay details in the booking URL. The
checkIn,checkOutandguestsquery parameters that §5.1 recommends put the quoted dates and guest count intodirect_booking_url, so they reach browser history and server logs wherever the URL is followed. - Correlation through the booking URL. The optional offer reference identifier in
direct_booking_url(§5.1) lets the host node correlate a booking-page visit with the offer it issued. It is not needed for verification (§5.1). This document sets no limit on how long such correlation data is kept; that is the host's decision.
Portable attestations and the transparency log carry their own privacy sections (attestations-v0.1 §9, transparency-log-v0.1 §9).
16. License
Specification text: dedicated to the public domain under CC0 1.0. Reference code and conformance test vectors: Apache-2.0 (ADR 0007 D7). Patents: a royalty-free patent non-assertion commitment is offered under the Open Web Foundation Agreement 1.0 (Patent-Only) — see PATENTS.md.