Reference · JSON Schema

A JSON Schema for travel itineraries

Roadbook ships an official JSON Schema (draft 2020-12) describing a complete travel itinerary: trip, travelers, days and items, bookings and tickets, transport, people, vehicles, checklists, contacts. It is the machine-readable companion of the specification.

roadbook.schema.json → Validate a file

Facts#

What the schema covers — and what it cannot#

The schema expresses structure: required fields, types, enum tokens (item types, statuses, ticket formats, roles…), date and time patterns, currency codes, nested entities ($defs for member, day, dayItem, booking, ticket, person, vehicle, transportDetails, brand…). Each property carries a description, which makes the schema usable as documentation for a model.

It cannot express integrity: id uniqueness within a collection, day dates inside the trip period, consistent day indexes, references (bookingId, stayBookingId, memberIds, personIds, vehicleId, chosenOptionId) resolving to existing entities. Those rules live in the specification and are checked by the reference validator. Use both.

Validate with a generic validator#

JavaScript, AJV:

import Ajv2020 from 'ajv/dist/2020.js'
import { readFileSync } from 'node:fs'

const schema = JSON.parse(readFileSync('roadbook.schema.json', 'utf8'))
const validate = new Ajv2020({ allErrors: true, strict: false }).compile(schema)

const trip = JSON.parse(readFileSync('my-trip.roadbook.json', 'utf8'))
if (!validate(trip)) console.error(validate.errors)

Python, jsonschema:

import json, urllib.request
from jsonschema import Draft202012Validator

schema = json.load(urllib.request.urlopen("https://roadbookformat.org/roadbook.schema.json"))
trip = json.load(open("my-trip.roadbook.json"))
for error in Draft202012Validator(schema).iter_errors(trip):
    print(list(error.absolute_path), error.message)

Then run the reference validator for integrity rules — in Node:

import { validateRoadbook } from './roadbook-validate.mjs'   // or the npm package @roadbookformat/validate
const { ok, errors, warnings } = validateRoadbook(trip)

Structured output with AI APIs#

The schema can be passed as the response format / tool input schema of AI APIs that support JSON Schema, so the model is constrained to emit a structurally valid Roadbook. Practical notes:

• Some providers restrict the JSON Schema subset (no pattern, every property required, additionalProperties: false…). In that case derive a simplified schema from this one for the constrained step, then validate the output against the full schema and the reference validator.
• Constrained decoding guarantees structure, not integrity: still run the validator for references, date ranges and id uniqueness, and feed errors back for repair.
• For long trips prefer generating in chunks (skeleton, then days) — see the AI page.

Versions#

The schema at the canonical URL always describes the current stable version and accepts older minor versions of the same major (their fields are a subset). New minor versions add optional properties only. See versioning and the changelog.