Concept · travel itinerary format

An open travel itinerary format

Roadbook is an open JSON interchange format for complete travel itineraries. This page explains what a travel itinerary format has to capture, why portability between applications matters, and how Roadbook is designed to serve as that common format.

The problem: itineraries are scattered#

A trip is a structured thing — dates, places, people, reservations, tickets, fallbacks — but it is almost never stored as one. The confirmation e-mails sit in a mailbox, the flight in an airline app, the hotel voucher in a PDF, the museum slot in a calendar, the rental car in another PDF, the agency's day-by-day program in a document, the budget in a spreadsheet. Each silo is fine on its own; together they are not an itinerary you can hand to anyone — not to a travel companion, not to another application, not to an AI assistant asked to "move day 3 to day 4".

Calendar files (iCalendar) carry events but nothing about bookings, tickets or who is traveling. GPS files (GPX, KML) carry geometry, not meaning. PDFs carry everything — for human eyes only. Travel apps store rich data, but in closed, proprietary structures that do not leave the app.

What a travel itinerary format needs#

Need	Why	In Roadbook
`schedule`	Day-by-day, timed items with a type and a lived status.	Day / DayItem — 34 item types, `planned · done · skipped · replaced`.
`transport`	Flights, trains, transfers with carrier, number, reference, both ends, timezones.	TransportDetails on items and bookings; local wall-clock times + IANA timezones; `endDate` for overnight legs.
`bookings`	Reservations with status, references, payment, check-in/out, cancellation terms.	Booking — `confirmed · to_book · optional · cancelled`, `payment`, `refs`, `rooms`.
`tickets`	Scannable codes with their real payload, per traveler, with seat and validity.	Ticket — QR, Code 128, PDF417, Aztec, EAN-13, DataMatrix.
`travelers`	Who is on the trip, with roles, and which items concern whom.	Member + `memberIds`; dietary and accessibility needs; loyalty programs.
`alternatives`	What to do when it rains, when something is closed, when everybody is tired.	Alternative (triggered fallback) and ItemOption (on-site choice).
`logistics`	Checklists, contacts, notes, useful apps, vehicles, people to meet.	Checklist, Contact, LogisticsNote, AppLink, Vehicle, Person.
`portability`	One self-contained document, readable by any tool, stable over time.	Plain JSON, `.roadbook.json`, declared `formatVersion`, additive minor versions.
`machine readability`	A schema to validate against, unambiguous dates, times and enum values.	JSON Schema 2020-12, ISO dates, `HH:MM` times, English tokens, validator.

Why a portable, interchange format#

A portable travel itinerary is one you own as a file and can move between tools without re-typing anything. An itinerary interchange format is the agreement that makes this possible: a published structure that a travel agency's back office, a booking system's export, a script, an AI assistant and a mobile player can all read and write the same way. The benefits are practical:

Travelers keep one document for the whole trip, open it offline, share it with companions, and are not locked into the app that produced it.
Travel applications can import itineraries produced elsewhere and export their own, instead of re-implementing every integration pairwise.
Agencies and tour operators deliver a structured program (with guides, transfers, vouchers) that any compatible player displays — without building their own app.
AI assistants can generate the itinerary directly in the target structure, validate it, and hand it over — the document is the deliverable.

How Roadbook answers it#

Open specification — field-level reference, JSON Schema, validator, examples; MIT licensed; no registration or permission required to implement a reader or a writer.
Complete — the itinerary and everything needed to live it: bookings, tickets, people, vehicles, fallbacks, checklists, contacts.
Versioned — formatVersion in every file; minor versions are additive; readers ignore and preserve unknown fields.
Vendor-neutral — the format is separate from the players that read it; the official player is one implementation among others.
AI-friendly — small, regular JSON with English tokens; a generate → validate → repair loop documented on the AI page.

A minimal itinerary#

{
  "formatVersion": "1.2",
  "id": "weekend-bruges",
  "name": "Weekend in Bruges",
  "start": "2026-09-12",
  "end": "2026-09-13",
  "members": [ { "id": "m1", "name": "Alex", "role": "owner", "kind": "adult" } ],
  "days": [
    { "id": "d1", "index": 1, "date": "2026-09-12", "title": "Canals and belfry",
      "items": [
        { "id": "i1", "time": "10:00", "title": "Canal boat tour", "type": "boat", "status": "planned" },
        { "id": "i2", "time": "12:30", "title": "Lunch", "type": "meal", "status": "planned" }
      ] }
  ]
}

Complementary standards: export the schedule as iCalendar for a calendar app, a driving day as GPX for a GPS — Roadbook is the source they derive from, not their replacement.

Next#

Why JSON for a travel itinerary — structure, validation, portability, AI generation.
Itinerary interchange between applications — agencies, booking systems, assistants, players.
The travel itinerary JSON Schema — validation and structured output.
AI-generated travel itineraries — the generate → validate → repair loop.