VRP Well-Known URI — vacation-rental.json — Specification v0.1
Status: Draft. The vacation-rental.json well-known URI suffix is registered in the IANA Well-Known URIs registry (provisional, 2026-08-19): https://www.iana.org/assignments/well-known-uris/
Published: 2026-06-19 (revised 2026-08-20)
Change controller: Vacation Rental Protocol (VRP) — Rouiada Abbas, author/maintainer; hello@vacationrentalprotocol.com
Canonical context: https://vacationrentalprotocol.com/contexts/v1
Repository: https://github.com/vacationrentalprotocol/vrp-spec
1. Scope
VRP defines the well-known URI suffix vacation-rental.json (RFC 8615). A client that already knows a host's domain issues a single request:
GET https://{host}/.well-known/vacation-rental.json
to discover, in one site-wide document, that the origin is a bookable vacation-rental node and how to interact with it. The model mirrors OpenID Connect discovery (/.well-known/openid-configuration): probe one URL, receive a structured configuration, with no per-host hard-coding.
- Applicable scheme(s):
httpsonly. - Media type:
application/json. - One origin per node. Each property is its own host-owned origin, so the document describes the whole site — the site-wide case RFC 8615 is intended for. There is no multi-publisher / shared-host concern.
2. The name
vacation-rental.json is the descriptive discovery document for a VRP node: it names the resource (a vacation-rental node's site-wide configuration), and it is the suffix the core VRP specification (v0.1.md §2) defines and that the reference implementation and verifier fetch in practice. It is registered by the Vacation Rental Protocol — the standard that defines it — as a descriptive resource name (cf. security.txt, assetlinks.json), not a generic land-grab.
For transition compatibility a node MAY additionally serve the same document at the longer alias /.well-known/vacation-rental-protocol.json; clients SHOULD use vacation-rental.json. Node identity is additionally published at the already-registered did.json (did:web), whose DID document advertises this resource via a service entry.
3. Resource format (informative)
The resource is a self-describing JSON object, versioned by $schema and schema_version. Discovery-relevant fields include:
protocol,protocol_version— identifies the document as VRP and its version.canonical_domain,node_id— the node's host-owned domain (v0.1 §2) and stable identifier.identity/did— the node'sdid:webidentity (see/.well-known/did.json).jwks_url— public keys (JWKS) used to verify signed artifacts.verified_stay_offer_endpoint— where a signed, verifiable stay offer is obtained.capabilities,endpoints— supported operations and their URLs.availability,pricing,policies,media— structured, public property facts.structure_declarations— falsifiable commercial-structure claims, each carrying its own class and verification procedure (seestructure-declarations-v0.1.md). Like every other field here, declarations gain no authority from this location (§4): verifiable-class claims are trusted by executing their procedures.
Clients MUST ignore unknown fields and MUST treat the document as advisory metadata only (see §4).
4. Trust model (normative)
Trust is not derived from the well-known location; its presence confers no authority. Authoritative offers are Ed25519-signed on the host's own domain and verify standalone against the node's published keys (jwks_url / did:web), independent of any central party. An optional public append-only Merkle transparency log (RFC 6962; see https://vacationrentalprotocol.com/spec/transparency-log-v0.1) records signed-artifact hashes so that after-the-fact tampering is detectable. A client SHOULD verify signatures; it MUST NOT treat the discovery document itself as proof of any claim.
5. Security & privacy considerations
- Served over
httpsonly. - The document is public, machine-readable metadata; it MUST NOT contain guest personal data or secrets.
- Verification keys are published separately (
jwks_url,did:web); key rotation is handled there, not in this document.
6. Reference implementation
HemmaBo (https://hemmabo.com) is the reference implementation. Live example:
curl https://villaakerlyckan.se/.well-known/vacation-rental.json
The same document is also served at the alias path /.well-known/vacation-rental-protocol.json for transition; new clients SHOULD use vacation-rental.json.
7. IANA considerations
This document is the specification reference for the provisional registration of the vacation-rental.json well-known URI suffix in the IANA Well-Known URIs registry (RFC 8615), registered 2026-08-19: https://www.iana.org/assignments/well-known-uris/ Registration history: https://github.com/protocol-registries/well-known-uris/issues/93 (closed).
- URI suffix:
vacation-rental.json - Change controller: Vacation Rental Protocol (VRP) — Rouiada Abbas; hello@vacationrentalprotocol.com
- Status: provisional (registered 2026-08-19)
- Specification document: this page.
License
Specification text: dedicated to the public domain under CC0 1.0. Reference code and conformance test vectors: Apache-2.0 (ADR 0007 D7).