Spec notes: deviations, extensions and open questions
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 #
-
Version pin (spec ambiguity). A UCP profile
versionmust be a date (^\d{4}-\d{2}-\d{2}$), and UCP-authored capabilities declare the version of the release that contains them. Lodging is in no release yet. We declare2026-09-30, the date of themaincommit we implemented against (UCP_VERSIONinadapter-ucp/src/constants.ts), and link to the/draft/docs. This needs revisiting when lodging ships in a release. -
Namespace. UCP reserves
dev.ucp.*. OpenBooking's additions usesh.openbooking.*(reverse-DNS ofopenbooking.sh, which we own). Extensions are versioned2026-10-02. -
Schema URLs. We cite
https://ucp.dev/draft/schemas/lodging/booking.json, which appears verbatim in the spec. The URLs…/schemas/lodging/policy_cancellation.jsonand…/schemas/common/payment_terms.jsonare inferred from the samesource/schemas/→/schemas/site layout. We omitspecURLs we could not confirm, sincespecis optional for business profiles.
1.2 Discovery (/.well-known/ucp)
#
-
REST only. Only the
resttransport is advertised underdev.ucp.lodging. Our/mcpendpoint exposes agent-friendly tools (search_availability, …). It is not the UCP MCP binding (create_booking_session, …), so advertising it as UCP MCP would be wrong. A2A is a separate binding and is not advertised under UCP. -
payment_handlersis{}. It must be present even when empty. Deposits use a token extension instead (§1.8). -
No signing keys. No
keys(JWK set) are published, and request/response signatures (Signature,Signature-Input,Content-Digest) are not implemented. -
Extension capabilities. We advertise
sh.openbooking.booking(extendsdev.ucp.lodging.booking) andsh.openbooking.availability(standalone). Their JSON Schemas are served by the deployment itself at{endpoint}/schemas/<name>.json, following the UCP extension pattern ($defs["dev.ucp.lodging.booking"]=allOfof the parent schema plus our fields).
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 #
-
Required on every write (stricter than UCP). We
require
Idempotency-Keyon all writes: create, update, complete and cancel. A missing key returns 400. The OpenAPI marks it required on create and update, the prose says "SHOULD support", and open PR #868 would make it optional on create and update. We chose the strict reading because agents retry. -
Conflict. Same key with a different body → 409
idempotency_conflict. Records are kept for 24h, the UCP minimum. -
Deviation: only successes are stored. UCP says to
return the cached result for a matching retry. We cache
successful results only. A failed call changes no
state (providers must be atomic), so a retry with the same key
re-executes. This lets an agent call
completewithout consent, ask the user, and retry with the same key plususer_confirmed: true. -
Replays return the current state of the same session,
not a stale snapshot. A replayed create shows
canceledif the hold has since expired. No second side effect happens. - Key scope. Keys are global per deployment, not per session. Reusing a key for a different operation is a conflict.
1.7 Messages and errors #
-
HTTP status.
-
Protocol errors:
validation_error→ 400,not_found→ 404,idempotency_conflict→ 409,provider_error→ 503. -
Business outcomes → 200. For operations on an
existing session, the response is the session with the error in
messages[]and the status unchanged. For create, it iserror_response({ ucp: { version, status: "error" }, messages }). - Spec ambiguity: the HTTP code for a business failure on create isn't stated. We use 200.
-
Protocol errors:
-
Codes.
slot_unavailable→ UCPinventory_exhausted,party_size_unsupported→occupancy_exceeded_capacity,payment_failed→payment_failed. Other codes pass through as OpenBooking codes (lowercase snake_case; UCPerror_codeis an open string). -
Severity. We only use
recoverable(fixable in-protocol: validation, consent, customer details, payment) andunrecoverable. We avoidrequires_buyer_inputandrequires_buyer_reviewbecause UCP tiesrequires_*tostatus: requires_escalation, which requires acontinue_url. -
messages[].suggested_next_action(EXTENSION). A plain-language recovery instruction for agents. It is not added to the root oferror_response, because that object hasadditionalProperties: false. -
Non-refundable disclosure. A non-refundable rate
produces a
warningwithpresentation: "disclosure"andcode: "dev.ucp.lodging.policy.cancellation", as the UCP docs describe.
1.8 Consent and payment (EXTENSIONS) #
-
user_confirmed: true(request field,sh.openbooking.booking).-
It is required on
POST …/complete. Without it the session staysready_for_completewith auser_confirmation_requiredmessage. -
It is required on
POST …/cancelfor a completed session. Releasing a hold doesn't need it. - UCP has no explicit-consent flag; this is the core "never auto-confirm" rule.
-
It is required on
-
payment_token(request field, complete).-
It pays a deposit that is due at confirmation. It stands in for
UCP
payment.instruments[]and payment handlers until a real payment-handler integration exists. - We deliberately do not guess the instrument/credential shape.
-
The demo provider accepts tokens starting with
tok_;tok_fail…is declined.
-
It pays a deposit that is due at confirmation. It stands in for
UCP
1.9 Cancellation policy #
-
policies[]entry.-
Contains
type: "dev.ucp.lodging.policy.cancellation",description: { plain }andrefundability.applies_tois not used, since there is one policy per session. -
refundabilityis restricted torefundable | partially_refundable | non_refundable. UCP uses an open string with these as examples.
-
Contains
-
Structured schedule (EXTENSION). We add
free_cancellation_until(date-time or null),late_cancellation_feeandno_show_fee(Money or null) to the policy entry. UCP only has free-text deadlines; structured schedules are proposed in PR #861 and issue #807. We'll align when they land.
1.10 Payment terms (deposits) #
-
Shape. One
payment.terms[]entry{ id: "deposit", title, description, schedules: [{ id, type, description, amount }] }. -
Schedule
type.immediatemeans due at confirmation;at_propertymeans payable at the venue. UCP precisely defines onlyimmediate. - Amount. Integer minor units.
-
selected_term_idis never set, because there is a single term.
2. MCP #
-
Not the UCP MCP binding. We expose seven
agent-optimised tools instead of UCP's session CRUD:
get_business_info,search_availability,hold_slot,confirm_booking,get_booking,reschedule_booking,cancel_booking. A UCP-conformant MCP binding could be added later as a separate adapter. -
Flatter inputs than core.
party_sizeis an integer andpreferencesmaps to coretags. -
Input validation runs in the handler.
- Tool input schemas are advertised to clients as normal JSON Schema, but the SDK-side validator is a pass-through.
-
Validation happens in our handler, so failures come back as
structured
{ code, message, suggested_next_action }results withisError: trueinstead of plain SDK text. -
Output schemas are declared and validated by the SDK on success.
The SDK skips output validation when
isErroris set.
-
Transport.
-
Stateless Streamable HTTP via
createMcpHandler, which serves both the2026-07-28era (no sessions) and the 2025 legacy era. -
The Host and Origin allow-list defaults to the
baseUrlhost plus localhost. - A stdio entry point is available for local clients.
-
Stateless Streamable HTTP via
-
Annotations.
cancel_bookingisdestructiveHint: true. Every mutating tool isidempotentHint: truebecause of the idempotency key.
3. A2A #
-
Agent Card. v1.0 card at
/.well-known/agent-card.jsonwithsupportedInterfaces[0] = { url: <base>/a2a, protocolBinding: "JSONRPC", protocolVersion: "1.0" }. The v0.3 fields (url,preferredTransport, …) are not emitted. The legacy/.well-known/agent.jsonis not served. -
Endpoint.
POST /a2a(JSON-RPC) implementsSendMessage. It is stateless: every call is answered with aMessage(ROLE_AGENT) holding aDataPartresult plus aTextPartsummary, never aTask. The operation is chosen by a DataPart{ "skill": "search_availability" | "hold_slot" | ..., ...args }, the same six operations as MCP, routed to the sameBookingService(idempotency, hold expiry anduser_confirmedapply unchanged). Business failures come back as a structurederrorin the message, not a JSON-RPC error. -
Errors and unsupported methods.
GetTask/CancelTaskanswer TaskNotFound (-32001), streaming and push answer UnsupportedOperation (-32004), unknown methods -32601. The v0.3 namesmessage/sendandtasks/*are accepted as aliases. -
Unverified against the proto. Part shape (
{ data, mediaType }),ROLE_AGENTand the error codes follow our reading of v1.0; re-check againsta2a.protoand a real A2A client before calling this stable. - Free text is not understood. A message without a DataPart skill gets a usage hint. There is no natural-language layer.
-
EXTENSION: MCP pointer.
capabilities.extensions[]includeshttps://openbooking.sh/a2a/extensions/mcp-endpoint/v1(required: false,params.url= the MCP endpoint). This is an informational pointer we defined. -
No security schemes.
securitySchemesandsecurityRequirementsare omitted because the demo has no auth.
4. Core model extensions with no UCP equivalent #
-
Explicit consent.
user_confirmedon confirm, and on cancel of confirmed bookings. -
Hold as a booking state. A hold is a booking in
status
heldwith a mandatoryexpires_at. Lifecycle:held → confirmed → cancelled, orheld → expired | cancelled. -
Venue time zone and currency.
Venue.timezone(IANA) andVenue.currencyare needed to interpret local slot times and amounts. -
Structured errors.
ErrorPayload={ code, message, suggested_next_action, retryable, details? }.
5. Open items to track upstream #
- UCP PR #868: making Idempotency-Key optional on create and update.
- UCP PR #870:
stay_dates.end_datesemantics. - UCP PR #861 and issue #807: structured cancellation schedules.
- UCP issue #858: accommodation type discriminator and tool naming.
-
UCP issues #317, #479 and #303: appointment and availability
capabilities. These could replace
sh.openbooking.availabilityandtime_slot. -
Lodging booking shipping in a tagged UCP release: re-pin
UCP_VERSION.
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:
-
Consent. USP has no "the buyer approved"
flag, and forbids a platform from claiming acceptance the business
cannot verify. So each business picks how a booking becomes real.
consent: 'action'(default): creating a booking holds the slot and returnsrequires_actionwith an action of typesh.openbooking.confirmationwhosecontinue_urlis the booking page's confirm page; the booking is confirmed only when the customer presses the button there.consent: 'commit': creating the booking confirms it, trusting the platform to have asked its user (the same trust the MCP tools place inuser_confirmed). Free cancellations always work; inactionmode a cancellation that costs a fee, and any reschedule, are left to the customer, and the catalog advertises rescheduling only incommitmode. -
Authentication.
platform_key_pop: the platform makes its own Ed25519 key and signs an RFC 9449 DPoP proof on every privileged request; the key's thumbprint is its identity. The proof must be for the public URL (baseUrlplus route), not the one a proxy forwards. Booking-scoped credentials are bound to that key (cnf.jkt), kept only as a hash, and never accepted as bearer tokens. A platform can only reach holds and bookings it created. A key is tied to the profile it first presented (trust on first use, per business). -
Extensions on USP's open objects:
sh.openbooking.suggested_next_actionon messages and problem details, andsh.openbooking.cancellation_termson a booking (what cancelling costs right now). - Deposits are not offered. Slots that need an online deposit are left out of availability and refused on booking: the payment flow is not built, and a platform must not be led into a dead end.
-
Platform profiles (spec 8.2.3, 8.3, 8.4). On a
privileged call the business fetches the platform's profile (named
in
USP-Agent) and negotiates: only capabilities both sides have are used, a platform that speaks a newer version getsversion_unsupported(400, naming the latest), and one with nothing usable for the operation getscapabilities_incompatible(a 200 outcome). The fetch is the one place a caller makes our server send a request, so it is locked down: https on port 443 to a host name only (no IP literals, credentials or fragments); DNS is resolved once and the request is refused if any answer is a private or special-use address; the connection goes to that validated address with the host name used for TLS, so a second DNS answer cannot redirect it; no redirects, a time and size limit and a JSON content type; answers are cached for the profile'sCache-Control(at least 60 seconds), failures briefly, and concurrent requests share one fetch. It only runs after the proof has checked out, and not for the public operations. A key is bound to a profile only after the profile fetched, so an unreachable one cannot become permanent. -
MCP binding (spec 9.2,
openrpc/usp-mcp.json), off unlesscreateUsp({ mcp: true })(server:usp: { mcp: true }; hosted: deployment optionuspMcp, for businesses that have USP on). It is a stateless Streamable HTTP MCP endpoint at<usp path>/mcp, advertised in the profile as a secondtransport: 'mcp'binding. It is a translation layer over the REST router, not a second engine: eachusp_*tool call becomes the REST request the same operation takes and runs through the same router, so validation, consent mode, idempotency, ownership, capability negotiation, state store andBookingServiceare the REST ones. Two things differ. (1) The MCP proof covers the whole argument object, so it is verified in the MCP layer (authenticateMcp:_meta.usp.profile,_meta.usp.authorization.{mechanism, credential, proof},audis<base>/.well-known/usp,usp_pover the arguments) and the resulting principal is handed to the router, which then skips looking for REST headers; only requests built inside the adapter can carry a principal. After the proof, profile fetch, trust-on-first-use binding and negotiation are shared code with REST. (2) Answers are wrapped: outcomes arestructuredContent(the REST body) plus a text block with each message, aNext:line and the JSON; protocol errors are JSON-RPC errors withdata.code,data.content(and oursuggested_next_action). We use the low-level MCPServerbecauseMcpServerturns anything a tool throws into anisErrorresult. Tools served: the services, availability, hold, release and booking tools of the three capabilities we advertise. Not served (an unknown tool,-32602with nodata.code, as 9.2.1 asks): the feed, waitlist, registry andconfirm_payment(not offered), andusp_bookings_confirm, which is business-only and has no authentication in the OpenRPC (REST keeps it behindbusinessAuth). Tool descriptions tell agents to get the user's explicit approval before booking, changing or cancelling, and thatrequires_actionmeans not confirmed. -
JSON-RPC numbers are not fixed by the spec except
-32602(unknown tool, unknown ids) and-32002(payment errors, which we do not serve; the MCP SDK also maps-32002to-32602). Ours:-32600invalid_request;-32602validation, not-found, bad profile URL, cursor, range and version errors;-32001authentication, proof and profile-trust errors;-32009idempotency and revision conflicts;-32029rate limits;-32000unavailable;-32603server_error. Clients branch ondata.code. -
revision/If-Match(5.6). We never return a bookingrevision(its absence tells platforms to write unconditionally), so a precondition cannot hold:If-Match(REST) and_meta.usp.if_match(MCP) on update, cancel and reschedule are refused withrevision_mismatch(412) instead of being ignored. This also changes REST, which used to ignoreIf-Match. A replay of a successful call that carries a precondition is refused too, where the spec says a replay must skip the check; fixing that needs revisions. -
Spec inconsistency: the OpenRPC (and the OpenAPI)
require
bookingin theusp_bookings_createresult, but 9.4.2 makes a taken slot or an expired hold a 200 withmessagesand no booking. We follow 9.4.2 (as REST already did), so those results do not validate against the result schema; the tests check the parts that are defined for them. The OpenAPI also documents no 200 forPOST /bookings. -
More authentication (10.1.6, 9.1.4), all opt in through
createUsp({ platformAuth })(or the options ofcreatePopAuthenticator). The default is unchanged: Ed25519 proofs only.-
ES256 proofs (
proofAlgorithms: ['EdDSA', 'ES256']). The spec says EdDSA is the floor and ES256 "MAY be accepted in addition", so listing ES256 without EdDSA is refused at start-up. Each algorithm names its key type and curve (OKP/Ed25519,EC/P-256); a key on another curve is refused, and only the key members go into the thumbprint. The accepted algorithms are announced in the RFC 9449WWW-Authenticate: DPoP algs="EdDSA ES256"challenge. Choice: we publish no field for them in the profile'sauthorizationpolicy, because the spec only says the open object "advertises" them and names no member. -
Nonce challenge (
nonces: { secret, windowSeconds? }). A proof without a validnonceclaim getsproof_nonce_required(401) and a nonce in the RFC 9449DPoP-Nonceheader, in anoncemember of the problem body (REST), and asdata.nonce(MCP, where the problem body becomes the error data). The spec does not say how a nonce is made or how long it lives; ours is stateless,step.HMAC(secret, key thumbprint, step), bound to the key it was issued to, accepted for the step it was issued in and the next one (default 5 minutes each), reusable inside that time becausejtistill makes every proof single-use. The check comes after the signature andiatand before thejtiis recorded, so a challenged proof does not burn itsjti. -
HTTP message signatures (
httpSignatures: true, REST only). RFC 9421,ES256(ecdsa-p256-sha256; we also read the JOSE nameES256inalg), keys from the platform profile (keys, thensigning_keys). Covered components are the spec's:@method,@authority,@pathalways, and@query,usp-agent/ucp-agent,idempotency-key,content-digest,content-typewhen the request has them; a signature that leaves one out issignature_invalid.@authority/@pathare built frombaseUrl, likehtu. The signature must be the fixed-width 64-byte form.Content-Digestis checked assha-256over the received bytes (digest_mismatch, 400). The platform's identity is the thumbprint of the profile key that verified, and the same trust-on-first-use key-to-profile binding as for proofs applies. The tests verify the ES256 request signature printed in RFC 9421 section 4.3 (test-key-ecc-p256), so the signature base is checked against a published value and not only against our own code. -
Where we went beyond or beside the spec, because it is
silent
(all of them fail closed): (1) exactly one signature (one label)
per request; (2) a request with a body must carry a
Content-Digest, since the body would not be protected otherwise; (3) a signed request that changes something must carry anIdempotency-Key(the spec says platforms SHOULD; we require it, withrequireIdempotencyKey: falseto relax it), because without a signature timestamp it is the only thing that stops a captured request from being replayed; (4)createdis not required, but a pastexpiresgivessignature_expired, andmaxAgeSecondsadds the freshness window the spec lets a business add; (5) a request that carries a DPoP proof or a credential is judged as proof of possession only, never rescued by a signature (downgrade resistance); (6) no booking-scoped credential is issued to a signing platform: it would have to be bound to a key it does not prove with, and an unbound one is a bearer token, so it reaches only what it created, by its own identity (the "equivalent per-resource check"); (7) the profile is fetched only after the signature headers parse, but before the signature is verified, because the keys are in it, so an unauthenticated caller can make us fetch a public profile URL (the fetcher is the hardened one and caches failures); (8)signature_invalidalso covers a published key that carries private members, andalgorithm_unsupported(400) a key of another type or algorithm. -
Open questions for the spec: how a business
advertises accepted proof algorithms and nonce support in the
authorizationpolicy; whether several signatures per request are meant to be combined, and which one a business must act on; whether a request with a body may omitContent-Digest; whetherexpiresin the past issignature_expired(the table says the code is forcreated, and "does not apply to request signatures"); whether the nonce also belongs in the REST problem body; which ofES256andecdsa-p256-sha256goes in thealgparameter.
-
ES256 proofs (
-
Gaps: HTTP message signatures over MCP (the
signature would be on the HTTP request of the MCP endpoint, which
that binding does not read), signing our own responses and webhooks,
signature-covered
@query-paramand other component parameters, the MCP transports other than HTTP (stdio), and OAuth/API-key/mTLS mechanisms are not done. Algorithms other than ES256 for signatures (RSA, Ed25519 keys in a profile) are skipped, as the spec lets a verifier do. -
Open upstream:
range_too_wideis 400 in the error registry (9.4.3) but 422 in the availability prose (we follow the registry); no code for an unknown hold id on release (we usebooking_not_found); the messageseveritylist in the prose includesunrecoverablebut the message schema's enum does not (we send no severity oncapabilities_incompatible).
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.