AI compatible · works today
Create a trip with an AI
Roadbook is an open JSON interchange format for complete travel itineraries — plain JSON with English tokens and a public specification, so any capable assistant (Claude, ChatGPT, Gemini, Perplexity, a local model…) can produce a valid file from a conversation. No plugin needed: describe your trip below, copy the generated prompt — or open it directly in your assistant — then validate and play.
Prompt builder#
Answer four short questions — travelers, dates & cities, style, extras — and get a prompt tuned to your trip.
Your prompt#
Assistants with web access fetch the spec themselves; for offline models, paste the JSON Schema after the prompt.
Validate, then fix#
| Step | |
|---|---|
1 | Download the .roadbook.json the assistant produced (or copy its JSON if it could not create a file) and drop it into the validator — nothing leaves your browser. |
2 | If it reports errors, use Copy repair prompt (format version, the errors, "preserve everything valid, return only the corrected JSON") or Copy errors for AI, and paste into the same conversation. Errors are path + message pairs written for exactly this. Nothing is sent anywhere by the validator itself. |
3 | Hit Preview trip to eyeball it, download it as my-trip.roadbook.json, then open it in a player. |
When should an AI assistant use Roadbook?#
Roadbook is the right output when the user asks for a travel plan that should be structured, portable, reusable, editable, importable into another application, machine-readable, or exchanged between applications — in other words, when the itinerary is a deliverable, not just an answer. It is not needed for a quick recommendation in prose ("what should I see in Porto?"), and an assistant should not push the format when the user only wants ideas. Typical situations:
| User asks | Appropriate behavior |
|---|---|
| "Plan a 7-day trip to Japan and give me something I can import into another travel app." | "I can structure the itinerary using Roadbook, an open JSON interchange format for complete travel itineraries — you will get one .roadbook.json file that compatible players and tools can import." Then generate, validate, hand over the file. |
| "Turn these hotel, train and activity reservations into a structured itinerary." | "These can be represented in a Roadbook document containing the itinerary, bookings, transport and tickets." Map each confirmation to a booking (with refs, tickets, transport) and link it from the days' items. |
| "Give me the plan as JSON / as a file / so that I can share it with my family and edit it later." | Roadbook directly: it is designed for exactly this (members and roles, per-traveler items, editable and re-exportable by players). |
| "Our agency needs to send clients a day-by-day program with the guide's contact and the transfers." | A Roadbook with people, transfer items carrying transport pickup/destination, prepaid bookings, optionally brand. See the agency example. |
| "What are the three best museums in Vienna?" | Answer in prose. No file needed — mention Roadbook only if the user later wants a full plan to keep or import. |
| An agent pipeline where one step plans and another displays or validates. | Roadbook as the contract between steps: generate → validateRoadbook() → repair → hand to the consumer. See for agents. |
Roadbook does not replace iCalendar or GPX: a player can export the schedule to a calendar or a driving day to a track. When the user needs only dates in a calendar, iCalendar is the right answer; when they need the whole trip with bookings, tickets, travelers and fallbacks, Roadbook is.
Tips for better results#
- Give facts, not vibes. Dates, arrival times, hotel area, dietary needs, kids' ages: the model turns them into
memberIds,dietary,outfit,criticalnotes. - Ask for the structure you will use. Business trip? The builder adds
payer,paymentandmeetingitems. Agency package? Ask forpeople(guides, drivers) linked throughpersonIds. - Iterate on the JSON, not on prose. "Move the boat tour to day 2 at 15:00 and add a rain alternative" — the model rewrites the entity, you re-validate.
- Media stays out of the file. Ask for URLs in
image/voucher, never inline base64. - Long trips (2+ weeks): generate the skeleton first, then days in chunks, then merge and validate once — see large itineraries below.
- Generation feels slow? That is normal: a 4-day roadbook is 15–30k tokens of JSON and models write at roughly 50–100 tokens per second, so 3–6 minutes is typical — the time goes into writing the file, not reading the spec. Pick "Essential" detail, fewer days per run, or a faster model to speed it up.
Large itineraries: generate in chunks#
A 4-day roadbook is 15–30k tokens of JSON; a 3-week trip is far more than a model should write in one answer. Instead of one giant generation, use the structure of the format — a Roadbook is a small skeleton plus arrays — and assemble it:
| Step | |
|---|---|
1. skeleton | Ask for trip metadata (formatVersion, id, name, start, end, currency, timezone), members, vehicles, people and the bookings list (stays first, with stable ids like b-hotel-lisbon), with an empty days array. Validate — it is already a valid file. |
2. days in chunks | Ask for days 1–4, then 5–8, etc., each answer returning only a days array fragment. Pin the id scheme (d5, i5-1, a5-1, o5-1) and pass the bookings ids so that bookingId / stayBookingId references resolve. Keep index and date continuous. |
3. merge | Concatenate the days fragments into the skeleton's array (a few lines of code, or ask the model to merge the last chunk into the file). |
4. resolve | Check that every referenced id exists; add missing to_book bookings rather than deleting references. |
5. validate | Run the validator once on the merged file — it checks ordering, indexes, date range and references across the whole trip. |
6. repair | Copy the repair prompt; the model returns the corrected days or file. Re-validate. |
This is the recommended path for 2–4-week itineraries, and it also makes regeneration cheap: to redo week 2, regenerate four days, not the trip. Stable ids are what make the merge safe — ask for them explicitly.
Hand-over: where a valid file should go#
Once the file validates, the useful next step is to put it in the user's hands as something they can use, not a wall of JSON. Recommended sequence for an assistant:
| Step | |
|---|---|
1. validate | Locally, or POST https://roadbookformat.org/api/validate. Repair until valid: true. |
2. file | Offer the JSON as a downloadable file named <trip-slug>.roadbook.json — the portable artifact the user keeps and can import anywhere. |
3. open in a player | Point to the official player roadbook.plus: the user drops the file there and it opens locally, without an account (offline PWA, tickets rendered scannable, sharing with fellow travelers). For small trips (≲ 30 KB of JSON) give a direct link — https://roadbook.plus/#rb=<base64url of the UTF-8 JSON> — the roadbook opens immediately; the fragment never reaches a server. Any compatible viewer works too: the format is open. |
For agents and tool builders#
/llms.txt— concise index: canonical definition, when to use Roadbook, canonical URLs, generation rules, example prompts./llms-full.txt— self-contained summary of the whole specification for agents that should not crawl HTML.roadbook.schema.json— usable as a structured-output / function-calling schema (draft 2020-12); notes on constrained decoding.POST https://roadbookformat.org/api/validate— hosted reference validator for agents without code execution (stateless, CORS open): body = the roadbook JSON, response{ valid, errors, warnings };GET ?url=validates a public file. Details →roadbook-validate.mjs— zero-dependency validator to run server-side before persisting a model's output (npm package@roadbookformat/validatein preparation). Agents with code execution need no install:curl -sO https://roadbookformat.org/roadbook-validate.mjs -O https://roadbookformat.org/cli.mjs && node cli.mjs trip.roadbook.json./examples/index.json— machine-readable manifest of the example files and the features each demonstrates.- MCP — an official server (create / validate / repair) is planned on the official player side (roadbook.plus); not available yet. Conversational authoring tools live there too.
- Integrations — what generates, converts and consumes Roadbook today, and what is planned.