Concept · itinerary interchange
Exchanging travel itineraries between applications
Roadbook is an open JSON interchange format for complete travel itineraries — an open, versioned JSON format for exchanging complete travel itineraries between AI assistants, travel applications, agencies and travelers. This page is about the exchange: who produces a Roadbook, who consumes it, and what makes the handover reliable.
Who exchanges what#
| Actor | Produces | Consumes |
|---|---|---|
travel agency / tour operator | The sold program as a Roadbook: days, guides and drivers (people), transfers (transport), vouchers (tickets), the organisation's brand. | Client changes re-exported from a player; itineraries drafted by an assistant. |
booking system / OTA | Exports of confirmed reservations as bookings with refs, payment, check-in/out, tickets with real payloads. | — |
AI assistant | Whole itineraries from a conversation; repairs after validation. | An existing Roadbook to edit ("move the boat tour to day 2"). |
itinerary builder | Hand-authored or wizard-built trips. | Imports to continue editing. |
mobile app / offline player | Edited, re-exported files (statuses updated, options chosen). | Any valid Roadbook: renders days, tickets as scannable codes, per-traveler views, offline. |
scripts, converters, analytics | Conversions from e-mails, PDFs, calendars (future); generated test trips. | Budget aggregation, calendar export, reporting. |
What makes the handover reliable#
- One document, one file.
.roadbook.json, UTF-8,application/json. No API to call, nothing to authenticate against: the file is the interface. - A published specification and schema. Producers and consumers agree on field names, enum tokens, date/time conventions and reference semantics. Spec · schema.
- Validation at the boundary. The reference validator runs anywhere JavaScript runs; integrity errors are explicit and actionable.
- Versioning that does not break. Every file declares
formatVersion; minor versions are additive; readers ignore and preserve unknown fields — a 1.0 player editing a 1.2 file must not erase 1.2 fields. Vendor extensions use a prefix (x-myapp-…). - Stable identifiers. Every entity has an
id; references (bookingId,memberIds,personIds,vehicleId) resolve within the file, so round-trips keep relations intact. - Media out of band. Images and vouchers are URLs or relative paths, so the document stays small and the exchange does not depend on one storage.
- Vendor-neutral by design. The format is separate from any player. Any application may implement Roadbook; no registration, API key or permission is required.
Three concrete scenarios#
- Agency → traveler → player
- The agency's system emits
marrakech-package.roadbook.jsonwith the program, the driver's photo and WhatsApp, prepaid transfers and Majorelle tickets. The traveler opens it in any compatible player; the file is read offline in the medina; the player shows "by Example Travel". Example → - Assistant → validator → player → assistant
- An assistant generates a 5-day Japan trip; the validator flags an unknown
bookingId; the assistant repairs it; the file is imported into a player; two days later the traveler asks the assistant to swap two museums — it edits the same file. Workflow → - Booking export → merge → business trip
- A corporate travel tool exports flights and hotel as
bookingswith company-paidpayment; the traveler's assistant adds meetings and a conference; the validated file is shared with the colleague on the same trip. Example →
Complementary formats#
Roadbook does not replace iCalendar, GPX/KML or airline boarding-pass standards; it references or derives them. A player may export the schedule to a calendar, a driving day to GPX, and renders IATA BCBP payloads as PDF417 — the Roadbook is the source of truth they derive from.
Implementing a reader or writer#
Requirements for claiming "Roadbook 1.2 compatible" are on the versioning page; the integrations page lists existing and planned tooling; submit your implementation to be listed.