OpenBooking / Docs / Spec notes
Guide

Spec notes: deviations, extensions and open questions

Last updated 2026-11-05 · Edit on GitHub

This document lists every place OpenBooking deviates from, extends, or interprets the specs it implements. In code, the same spots are marked // EXTENSION: or SPEC AMBIGUITY:.

Specs as implemented (checked 2026-10-02):

Spec Version / source Status in OpenBooking
UCP lodging booking dev.ucp.lodging.booking UCP main @ b0e81ade (2026-09-30), draft, not in any release (latest release 2026-08-25) REST binding implemented (draft)
UCP cancellation policy dev.ucp.lodging.policy.cancellation same implemented, with an extension
UCP payment terms dev.ucp.common.payment.terms same deposits only
MCP protocol 2026-07-28 and the 2025 legacy versions, via @modelcontextprotocol/server 2.2 implemented
A2A v1.0 (protocol version "1.0"), specification/a2a.proto Agent Card plus SendMessage (stateless)

1. UCP #

1.1 Versioning and namespace #

1.2 Discovery (/.well-known/ucp) #

1.3 Availability search: sh.openbooking.availability (EXTENSION) #

UCP has no availability or search capability. The lodging roadmap lists discovery as future work, and issues #317, #479 and #303 propose one. We add:

GET {endpoint}/availability?date=YYYY-MM-DD&party_size=N[&time_from=HH:MM][&time_to=HH:MM][&offering_id=][&tags=a,b][&venue_id=][&limit=]
→ { ucp, property, offers: [ stay-shaped offer … ] }

Each offer reuses the stay shape (id, stay_dates, accommodation_type, rate_plan, occupancy, totals) and adds time_slot, currency, policies and payment_terms. Its id is the opaque slot id, which is passed back as stays[0].id on create.

1.4 Booking sessions #

Topic UCP OpenBooking
Hold No hold object. expires_at covers "session state, quoted pricing, and any temporary inventory holds". A session in incomplete/ready_for_complete is the hold. The inventory is reserved exclusively until expires_at (default 10 min). Cancel releases it early.
Create input stays[].id or accommodation_type.id + rate_plan.id Only stays[].id (an offer id from /availability), and exactly one stay
property required on create Optional. If sent, property.id must match the slot's venue, otherwise validation_error (the hold is rolled back)
guests[], guest_assignments, travel_purpose, context, signals optional Accepted and ignored
booker lead contact Maps 1:1 to the core Customer (first_name, last_name, email, phone_number). We enforce UCP's lead rule: name plus email or phone before completion.
PUT (full replacement) replaces the session Only booker changes are applied. A different stays → operation_not_supported (cancel and create a new session). Other fields are ignored rather than cleared.
accommodation_type room type { id: resource kind ("table"), title: "Table for up to 4" }. This is a semantic stretch for tables and staff.
rate_plan rate plan { id: offering id, title: offering name } (e.g. "Dinner", "Chef's tasting menu")
occupancy adults, children, child_ages, total total, plus adults/children when known. Agents usually only know a party size.
stay_dates date_interval; end_date semantics undefined (PR #870) Spec ambiguity. Both are the venue-local dates of slot start and end, so same-day slots have start_date == end_date.
stays[].time_slot — EXTENSION { start_at, end_at, timezone }, because sub-day bookings need times.
links required Always []. We have no ToS or privacy links yet.
continue_url SHOULD be present for non-terminal statuses Omitted. There is no business web checkout to hand off to.
currency required From Venue.currency (core EXTENSION: UCP property has no currency), with fallback to slot amounts
totals exactly one subtotal and one total When the price is unknown up front (pay at venue), both are 0 with display_text: "Pay at venue" / "Total due now". This is our interpretation.
confirmation { id, label, … } on completed { id: confirmation_code, label }
Response ucp only version required { version, capabilities: { <active name>: [{ version }] } }. We don't know the exact expected shape of the active-capabilities list.

1.5 Status mapping #

Core UCP
held, no customer incomplete (plus a customer_details_required message, path: $.booker)
held, with customer ready_for_complete
confirmed completed
cancelled, expired canceled (an expired hold adds an info message)

requires_escalation and complete_in_progress are never produced, because confirmation is synchronous and there is no business UI handoff.

Cancelling a completed session (spec ambiguity). UCP doesn't say whether cancel applies after completion. We allow it and apply the cancellation policy. This is an extension.

1.6 Idempotency #

1.7 Messages and errors #

1.9 Cancellation policy #

1.10 Payment terms (deposits) #


2. MCP #

3. A2A #

4. Core model extensions with no UCP equivalent #

5. Open items to track upstream #

6. USP (Universal Scheduling Protocol, draft) #

@openbooking-sh/adapter-usp follows the USP draft (version 2026-08-20, validated offline against the schemas, OpenAPI document and test vectors vendored from wix/universal-scheduling-protocol at the commit in USP_SPEC_COMMIT; the spec has changed without a version bump, so the commit is the pin). Choices that are ours:

7. Pins and upstream watch #

Every protocol we implement or watch, with its pinned version or commit and its source, is listed in PROTOCOLS.md. A weekly job (scripts/watch-protocols.mjs) compares each upstream with those pins and files an issue when a watched spec file or release changed.

This page is generated from docs/SPEC-NOTES.md in the open-source repository. To fix something, change it there.