An open format for playable travel itineraries

One trip, one JSON file.

Roadbook describes a complete trip — day-by-day schedule, bookings, scannable tickets, weather fallbacks, on-site options, people to meet, checklists — in a single JSON document. Human-readable, written by hand, by a script or by an AI, and consumed by offline-first "player" applications.

spec v1.2 license MIT schema JSON Schema 2020-12 validator zero-dependency ESM AI compatible

Generate a trip with an AI → See a roadbook Read the spec

Open & documented

Full field-level specification, official JSON Schema and validator with built-in preview. MIT licensed — no vendor, no account, no lock-in.

AI-compatible by design

Plain JSON with English tokens, one documented URL to feed a model, and validator errors written to be pasted back for self-correction. Prompt builder — open in ChatGPT / Claude →

Cross-vertical: personal & professional

Same file for a family road trip, a business trip (payer, payment status, meetings, loyalty programs) or a package sold by an agency (guides to meet, transfers, structured transport).

Versioned by design

Every file declares its formatVersion. Minor versions are additive; players advertise the highest version they support. Rules →

Built for the road

QR / Code 128 / PDF417 / Aztec tickets carrying their real encoded payload, vouchers, GPS coordinates, timezones, conditional fallbacks (rain, closure…), options decided on-site.

Multi-traveler

Members with roles (owner, editor, viewer), per-traveler tickets and items, and a spoiler-free "surprise mode" for kids.

One format, every kind of trip#

Roadbook is transverse: it is not tied to a travel style, a vendor or a distribution channel. The same schema, the same players.

Context	What the format carries
`personal`	Family road trip, city break, honeymoon: itinerary, hotel bookings, kids' surprise mode, "what to wear today", plan B when it rains, on-site restaurant options, budget.
`professional`	Business travel: flights with PNR / terminal / gate, meetings and conferences as first-class items, `payer` (personal / company), payment status, expense-friendly prices, loyalty numbers per traveler.
`agency / operator`	A tour operator hands its customer one file: guides and drivers to meet (with photo and recognition sign), transfers, vouchers, emergency contacts — playable offline in any compatible app instead of a PDF.
`AI assistant`	A conversation with an LLM ends with a valid `.roadbook.json`, checked by the validator and opened in a player — see AI.

What it looks like#

{
  "formatVersion": "1.2",
  "id": "bruges-weekend",
  "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",
          "place": "Huidenvettersplein, Bruges",
          "alternatives": [
            { "id": "a1", "trigger": "rain",
              "title": "Groeninge Museum instead" }
          ] },
        { "id": "i2", "time": "12:30", "title": "Lunch",
          "type": "meal", "status": "planned",
          "options": [
            { "id": "o1", "title": "De Halve Maan", "place": "Walplein 26" },
            { "id": "o2", "title": "That's Toast", "place": "Dweersstraat 4" }
          ] }
      ]
    }
  ]
}

Full-featured example: demo.roadbook.json (4 days Lille → Bruges → Amsterdam: bookings, tickets, people, vehicles, checklists) — preview it.

Quickstart#

Step
`1. write`	Author a trip in JSON following the spec — or hand the prompt to an AI and let it generate the file. Recommended extension: `.roadbook.json`.
`2. validate`	Run the official validator (browser or `node cli.mjs trip.roadbook.json`): structure, date/time formats, reference integrity.
`3. preview`	Hit Preview trip in the validator — a plain, read-only rendering to eyeball the result.
`4. play`	Load the file into a compatible player: web, mobile, offline, synced across travelers.

Why not iCal, GPX or a PDF?#

Format	What it lacks for a trip
`PDF / email`	Not machine-readable: no tickets that render as scannable codes, no per-traveler view, no live status, no offline sync.
`iCal`	Events with a time — but no bookings, tickets, fallbacks, options, roles, checklists or itinerary semantics.
`GPX / KML`	Geometry only: tracks and waypoints, nothing about what happens there, when, with whom, or with which reservation.
`roadbook`	The itinerary and everything needed to live it, in one versioned JSON that any tool — including an LLM — can read and write.

Ecosystem#

The format is the open foundation of an ecosystem: players (the official Roadbook player — offline-first PWA in production use, which validates the spec — and compatible viewers, yours included), generators (scripts, AI assistants, and the conversational builder shipped with the official player), and third-party tooling. Any application reading or writing this format may advertise itself as "Roadbook ≤ 1.2 compatible" — see versioning.

FAQ#

Is it free?: Yes — specification, schema, validator and examples are MIT licensed. Build a player, a generator or a commercial product on top of it.
Where do images and PDFs live?: Outside the file: image and voucher fields are URLs (or data-URLs for tiny assets). The JSON stays small enough to fit in an LLM context or a sync payload.
Are the tickets real?: Yes — a ticket carries its actual encoded payload and barcode format; a player renders a scannable code from it, offline.
Can I add my own fields?: Yes. Players must ignore — and preserve — unknown fields. Prefix vendor extensions (e.g. x-myapp-…) to avoid future collisions.
Is there a machine-readable summary for AI tools?: /llms.txt lists the canonical URLs of the spec, schema, validator and examples.