Specification · Markdown source · Edit on GitHub · CC0 1.0

VRP Node Structure Declarations — Specification v0.1

Status: Public draft Published: 2026-07-04 Canonical URL: https://vacationrentalprotocol.com/spec/structure-declarations-v0.1 Repository: https://github.com/vacationrentalprotocol/vrp-spec

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in RFC 2119.

1. Scope

This section defines falsifiable node structure declarations: a small set of binary commercial-structure claims a VRP node publishes about itself, where every claim ships with its own verification procedure that any agent — or any human with a browser — can execute against the node itself. No third party, no issuer, no registry.

Core VRP proves that a concrete offer is real (signature, freshness, exact price). Structure declarations answer the question an agent asks *before* quoting a node at all: *what kind of commercial thing is this?* Is it a marketplace? Does it take a commission? Is anyone gatekeeping the traversal? Each answer is published as a claim that is either verifiable by execution or attested by the node — and the two are never allowed to look alike.

Non-goals, inherited from VRP's core scope (v0.1 §1):

2. Location

Structure declarations are published as the OPTIONAL top-level object structure_declarations in the node's discovery document /.well-known/vacation-rental.json (see the Well-Known URI specification §3).

"structure_declarations": {
  "is_marketplace":    { "value": false, "class": "verifiable",
    "verify": "Booking and checkout endpoints resolve on canonical_domain; the traversal contains no third-party redirect." },
  "commission_pct":    { "value": 0, "class": "verifiable",
    "verify": "In the signed verified_stay_offer, agent_total equals the amount charged; the pay-to destination is bound to the host's account inside the signed payload." },
  "source_of_truth":   { "value": true, "class": "verifiable",
    "verify": "did:web resolves on this domain; the JWKS is live; the offer signature validates against the domain's published keys." },
  "gatekeeper":        { "value": "none", "class": "verifiable",
    "verify": "The full agent traversal (discover → verify keys → signed offer → checkout) completes with zero external authority, registry, or API key." },
  "price_integrity":   { "value": "single_total", "class": "verifiable",
    "verify": "The total in the signed offer equals the total at checkout; no add-on fees appear between offer and payment." },
  "surface_consistency": { "value": "contract-tested", "class": "attested",
    "verify": "Agent-facing surfaces read attested claims only, never free text; enforced by the node's CI contract tests. Host-attested — not independently executable." }
}

The trust model of the Well-Known URI specification (§4) applies unchanged: the discovery document's location confers no authority, and a client MUST NOT treat the document itself as proof of any claim. A structure declaration earns trust in exactly one of two ways, by class:

3. Field definitions

structure_declarations is a JSON object. Each member maps a declaration key (§6) to a declaration object with exactly these members:

Clients MUST ignore unknown members of a declaration object.

3.1 Registered declaration keys (v0.1)

KeyValue typeMeaning when declared
is_marketplacebooleanfalse: the node is a single host-owned origin selling its own inventory — not a venue listing third-party inventory.
commission_pctnumberThe percentage taken by any party between the guest's payment and the host for a direct booking on this node. 0 means the host receives the full amount charged.
source_of_truthbooleantrue: this domain is the authoritative source for its own offers — identity, keys, and signatures all resolve here.
gatekeeperstring"none": no external authority, registry, membership, or API key is required at any step of the agent traversal.
price_integritystring"single_total": the signed offer's total is the checkout total; no fees are added between offer and payment.
surface_consistencystring"contract-tested": agent-facing surfaces render only attested claims, never free text; the guarantee is the node's own CI, hence attested-class.

Suggested verification procedures for the verifiable keys are given in the example in §2; a node MAY word its procedures differently, subject to §5. surface_consistency is inherently attested-class: its guarantee lives in the node's internal CI and cannot be executed by an outside party.

All keys are OPTIONAL. A node SHOULD declare only what it is prepared to stand behind: a key that is absent is Unknown — a verifier MUST NOT infer an absent declaration as either true or false (the same tri-state discipline as attested claims, Portable Attestations §5).

4. Three-class taxonomy (normative)

Every declaration MUST carry exactly one class, and classes MUST NOT be conflated in presentation:

Rules:

5. Verification procedures (v0.1: prose)

In v0.1 the verify member is prose: a human-auditable, plain-language description of the procedure. Machine-executable descriptors (for example HTTP request templates with assertions) are deferred to a later revision and will be additive when they come.

A verify procedure MUST:

For attested-class declarations the verify member MUST instead state plainly what guarantees the claim and why it is not independently executable (see surface_consistency in §2 for the canonical form).

6. Extensibility and naming discipline

Extension keys follow the claim-key discipline of Portable Attestations §5, adapted to typed values:

7. Verifier presentation

A verifier that surfaces structure declarations:

Whether a node MUST keep its declarations consistent with observable behavior as a conformance criterion — and how conformance failures are reported — is deliberately left open in v0.1 (issue #60, open question 3). The falsifiability requirement in §5 already gives every verifier the tool to answer the question for itself.

8. Reference

Villa Åkerlyckan (villaakerlyckan.se) is the intended first live node for structure declarations. Publication on the node and the in-browser verifier extension are implementation steps tracked separately (issue #60, scope items 3–4); this document intentionally precedes them.

License

Specification text: dedicated to the public domain under CC0 1.0. Reference code and conformance test vectors: Apache-2.0 (ADR 0007 D7).