RoadBook

RoadBook for developers

The technical, open-source base of the project lives at roadbookformat.org (specification, schema, validator, examples, license). This page is the short version for people who want to read, write or hand over RoadBook files from an application, agent or service. The format is open (MIT), versioned and validated by a zero-dependency reference library. RoadBook+ is the official player — one implementation among the compatible viewers the format allows.

1. Write a RoadBook

Produce a JSON document that validates against the JSON Schema (draft 2020-12) with "formatVersion": "1.2". With an LLM, pass the schema as structured-output / tool schema and the spec URL in the system prompt; with code, any JSON library will do. Rules that trip up generators most: 24-hour HH:MM times, English enum tokens, unique ids, resolving references (bookingId, memberIds…), dates inside the trip period.

2. Validate

# Two files, no dependencies (Node ≥ 18)
curl -sO https://roadbookformat.org/roadbook-validate.mjs -O https://roadbookformat.org/cli.mjs
node cli.mjs trip.roadbook.json      # exit 0 = valid, 1 = errors, 2 = unreadable

// or in JS (browser or Node)
import { validateRoadbook } from './roadbook-validate.mjs'
const { ok, version, errors, warnings } = validateRoadbook(JSON.parse(text))
// errors: [{ path: "$.days[2].date", message: "…" }]

# or over HTTP (stateless, CORS open)
curl -X POST https://roadbookformat.org/api/validate -H 'content-type: application/json' --data @trip.roadbook.json

RoadBook+ embeds the very same validator: what passes there opens here. A web validator with “Copy repair prompt” is at roadbookformat.org/validator.html.

3. Hand the file to the user

  • File: offer <trip-slug>.roadbook.json for download and point the user to roadbook.plus/open — drag & drop, no account.
  • Direct link (small trips, ≲ 30 KB): https://roadbook.plus/#rb=<base64url of the UTF-8 JSON> — opens immediately; the fragment never reaches our servers. base64url = base64 with +→-, /→_, padding optional.
  • Any compatible viewer: the format is open; see viewers & players.

4. Read a RoadBook

Readers must ignore unknown fields (forward compatibility within a major version) and should preserve them when writing back. Absent formatVersion means 1.0; absent currency means EUR. Times are wall-clock local to the place; use the IANA timezone fields for cross-timezone math. The specification lists every field with its “since” version.

5. Examples & fixtures

  • japan-12-days.roadbook.json — the player's demo and regression fixture (12 days, flights, trains, stays, tickets in four barcode formats, options, plan B, budget).
  • Nine official examples on roadbookformat.org with a machine-readable examples/index.json manifest.

6. The RoadBook connector (MCP)

RoadBook+ exposes a public MCP server, so ChatGPT, Claude and any MCP client can learn the format, validate a file and show the roadbook inline in the conversation (MCP Apps), with a link that opens it in the player:

https://roadbook.plus/api/mcp        # Streamable HTTP, stateless, no authentication

tools:
  get_roadbook_guide     rules + canonical URLs to produce a valid RoadBook 1.2
  get_example_roadbook   a small valid example to start from
  validate_roadbook      { roadbook } → valid, version, errors[path, message], warnings
  preview_roadbook       { roadbook } → interactive read-only preview (ui://roadbook/preview.html)
                         + open link https://roadbook.plus/open#h=<id>&k=<key> (24 h, encrypted)
  • ChatGPT: Settings → Apps & connectors → Advanced → Developer mode → Create, URL https://roadbook.plus/api/mcp, no auth. Then “use RoadBook” in a chat: plan, validate, preview.
  • Claude: Settings → Connectors → Add custom connector, same URL. Claude Desktop / Code: claude mcp add --transport http roadbook https://roadbook.plus/api/mcp.
  • Privacy: the roadbook passes through the server only for the duration of the call; the preview link stores an AES-GCM ciphertext for 24 hours and the key lives in the link fragment only. Nothing is logged. Widget: self-contained, read-only.

7. For AI agents

Status & roadmap

Stable: format 1.2, validator, web API, this player, the MCP connector. In preparation: public GitHub repository for the specification and validator, npm package @roadbookformat/validate. Not yet: public sharing pages with indexable previews (planned with explicit publish, unguessable ids and privacy-safe metadata). Nothing here requires registration or a key; questions and integration requests: contact.