Reference implementation

Official validator

Paste the contents of a .roadbook.json file, drop the file below, or start from an example. Structure, formats and reference integrity are checked locally, in your browser — nothing is sent to any server.

examples ⤓ ⤓ ⤓ all 9 examples →

drop a .roadbook.json file here — or paste JSON below

Fix it with an AI#

When a file fails, two buttons appear under the errors. Neither sends anything anywhere — they only copy text to your clipboard for you to paste into the assistant that produced the file:

Button	What it copies
`Copy errors for AI`	A short block: "The following Roadbook validation errors must be fixed: …path: message… Return the complete corrected Roadbook JSON. Do not change unrelated information." — for an assistant that already has the file in its conversation.
`Copy repair prompt`	A complete, deterministic prompt: the target `formatVersion`, the errors and warnings, the rules (preserve valid content, stable ids, no invented data, return only JSON) and the JSON itself — for a fresh conversation or a different assistant.

The following Roadbook validation errors must be fixed:
$.days[2].date: Day 2026-10-16 falls outside the trip period (2026-10-10 → 2026-10-14).
$.days[2].items[1].bookingId: References an unknown booking: "b7".

Return the complete corrected Roadbook JSON.
Do not change unrelated information.

Validation is local by design. The full generate → validate → repair workflow is described on the AI page; for long trips see generate in chunks.

HTTP API — for agents and tools#

For AI agents and tools that can only make HTTP calls, the same reference validator is exposed at https://roadbookformat.org/api/validate. It is stateless — nothing is stored — and CORS is open. Local validation (this page, the CLI, the ESM module) remains the primary path; the endpoint is a convenience for agents without code execution.

# POST the roadbook JSON (or { "roadbook": … }) — response: { valid, version, errors, warnings }
curl -s -X POST https://roadbookformat.org/api/validate \
     -H "Content-Type: application/json" --data-binary @my-trip.roadbook.json

# or validate a public file by URL
curl -s "https://roadbookformat.org/api/validate?url=https://roadbookformat.org/examples/demo.roadbook.json"

# GET without parameters returns a usage document

errors make the file invalid, warnings keep it playable; both are path + message pairs. Limits: 2 MB, https URLs only for ?url=. Once the file is valid, the recommended next step for an assistant is to hand it to the user and open it in the official player roadbook.plus (drop the file, or https://roadbook.plus/#rb=<base64url of the JSON> for small files — see hand-over).

Command line#

node cli.mjs my-trip.roadbook.json
# exit code: 0 = valid, 1 = errors, 2 = unreadable

As a library#

The module roadbook-validate.mjs (ESM, zero-dependency, MIT) works in browsers and Node:

import { validateRoadbook } from './roadbook-validate.mjs'

const { ok, version, errors, warnings } = validateRoadbook(trip)
// errors/warnings: [{ path: "$.days[0].items[2].time", message: "…" }]

The JSON Schema (draft 2020-12) can also be used with any generic validator (AJV, python-jsonschema, …) — the reference implementation additionally checks cross-entity integrity that a schema cannot express. Snippets: JSON Schema page. An npm package (@roadbookformat/validate) wrapping this module is in preparation.

Validate from a URL#

Append ?url= to this page to prefill it with a remote file (the host must allow cross-origin reads): validator.html?url=https://example.org/trip.roadbook.json. Or ?example=demo to load a bundled example. Add &preview to open the preview right away.