# Vacation Rental Protocol - Specification v0.1 **Status:** Public draft **Published:** 2026-05-20 **Canonical URL:** https://vacationrentalprotocol.com **Repository:** https://github.com/HemmaBo-se/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; MCP can expose future tool bindings; and A2A can carry future agent-to-agent negotiation. VRP v0.1 does not define those runtime flows. ## 2. Discovery Document A VRP host domain publishes: ```text https://{host-domain}/.well-known/vacation-rental.json ``` Required fields: - `protocol`: MUST be `vacation-rental-protocol`. - `protocol_version`: MUST be `0.1`. - `canonical_domain`: MUST match the host-owned domain being verified. - `jwks_url`: MUST point to the host-domain JWKS. - `verified_stay_offer_endpoint`: MUST point to the host-domain verified stay offer endpoint. Recommended fields: - `node_id` - `capabilities` - `operator` - `endpoints` ## 3. JWKS A VRP host domain publishes an Ed25519 public key set: ```text https://{host-domain}/.well-known/jwks.json ``` Keys used for signing verified stay offers SHOULD use: - `kty`: `OKP` - `crv`: `Ed25519` - `use`: `sig` - `alg`: `EdDSA` - `kid`: stable key identifier ## 4. Verified Stay Offer Endpoint The verified stay offer endpoint accepts at least: - `check_in`: arrival date in `YYYY-MM-DD` - `check_out`: departure date in `YYYY-MM-DD` - `guests`: 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 SHOULD include: - `kind`: `verified_stay_offer` - `protocol_version`: `0.1` - `canonical_domain` - `node_id` - `generated_at` - `valid_until` - `request` - `property` - `availability` - `price` - `booking` - `agent_permission` ## 6. Freshness Agents MUST treat an offer as non-quoteable if `valid_until` is missing, malformed, or expired. 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 may quote an offer as an official host-domain verified offer only when all of the following are true: - The discovery document is fetched from the host-owned 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. - `valid_until` is present and fresh. - `availability.available` is true. - `price.exact` is true. - A direct booking URL is present. - `agent_permission.may_quote_as_official_direct_offer` is true. When safe, the canonical phrase is: ```text 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.available` is true and agent permission allows quoting. - Quote a final total unless `price.exact` is true in the signed offer. - Route booking action anywhere except the signed direct booking URL. ## 8. Fail-Closed Behavior Agents and clients MUST fail closed. If signature verification, freshness, 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](../examples/three-state-verification.md). ## 10. 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](./attestations-v0.1.md). ## 11. Reference Proof Villa Åkerlyckan is a live proof node: ```text 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. ## 12. License Apache 2.0 - see [LICENSE](../LICENSE).