An open standard for publishing bookable stays.

stays-protocol is a tiny, self-explanatory JSON format you put at /stays.json on your own domain. Any aggregator — roost or anyone else — can discover, parse, and link guests to your direct booking page. No platform owns it. No fees attach. The protocol is public domain under CC0.

Design principles

1. One file, one domain. A host publishes one stays.json at the root of their site. That's the whole listing.
2. The host's domain is the source of truth. Not roost. Not Airbnb. Not anyone else. The aggregators are caches; the host is canonical.
3. Bookings go direct. Every stay has a book_url that points to the host's site. Aggregators link out. No checkout flows through any third party.
4. Availability is open via iCal. Each stay optionally exposes an ical_url the aggregator can read. The host controls what's bookable.
5. No protocol-mandated fees. Aggregators must not charge per-booking commission to use stays-protocol data. (If they do, the spec recommends excluding them from federation discovery.)
6. Forward-compatible. Unknown fields are preserved by conformant parsers. Aggregators don't break when a host adds a new field.

Discovery

An aggregator MAY find a host's manifest by trying, in order:

1. https://host.tld/stays.json
2. https://host.tld/.well-known/stays
3. An HTML <link rel="alternate" type="application/json" href="..."> in the host's homepage
4. A DNS TXT record at _stays.host.tld pointing to a manifest URL

Aggregators SHOULD respect Cache-Control headers. Hosts SHOULD update at most every 5 minutes for sanity.

Manifest schema

Top-level object has 3 required keys: protocol, host, stays.

host (object)

stays (array of objects)

Minimal example

{
  "protocol": "stays-protocol/1.0",
  "host": {
    "id": "wishwood",
    "name": "Wishwood Glamping & Forestry",
    "domain": "https://wishwood.co.uk",
    "location": "Canterbury, Kent · England"
  },
  "stays": [
    {
      "id": "hobbit",
      "name": "The Hobbit Hut",
      "type": "hut",
      "sleeps": 3,
      "price_from": 95,
      "off_grid": true,
      "dogs": true,
      "ical_url": "https://wishwood-engine.workers.dev/ical/hobbit",
      "book_url": "https://wishwood.co.uk/book/hobbit"
    }
  ]
}

Verifiable provenance (optional)

A host MAY sign the manifest hash with an Ed25519 key and publish the public key at /.well-known/stays-key. Aggregators that verify signatures display a "verified" badge. Useful when listings get scraped and misrepresented elsewhere.

Versioning

This is stays-protocol/1.0. The protocol field at the manifest root declares conformance. Aggregators that find an unknown version MUST refuse to syndicate (graceful fail, not silent misinterpretation).

License

The protocol is released under CC0 1.0 Universal. Use it, fork it, embed it. No attribution required (though always nice).