Compatibility policy
Versioning
The format evolves without breaking existing files. Every roadbook declares its MAJOR.MINOR version in the root field formatVersion (absent = "1.0").
Rules#
| Increment | Meaning |
|---|---|
MINOR1.0 → 1.1 |
Backward-compatible additions: new optional fields, new optional values. A 1.1 file remains playable by a 1.0 player: unknown fields are simply ignored. |
MAJOR1.x → 2.0 |
Breaking changes: new required field, renamed or removed field, changed semantics. A 1.x player must not claim to read a 2.0 file. |
Player obligations#
| # | Obligation |
|---|---|
1 | Ignore unknown fields — never reject them, and preserve them when rewriting the file. A 1.0 player editing a 1.1 file must not erase 1.1 fields it does not understand. |
2 | Advertise compatibility — as "Roadbook ≤ 1.2 compatible": the highest version whose fields the player fully implements. It must accept any file of the same major version, even newer, surfacing when recent fields are not displayed. |
3 | Write the version it uses — a player producing a file writes the formatVersion matching the fields it actually emitted. |
History#
| Version | Date | Changes |
|---|---|---|
1.2 |
2026-08 | Universality release (all additive): IANA timezone fields (trip/day/item/transport points) with local wall-clock semantics and endDate for D+1 arrivals; coords on items and options; new Person (on-site guides/drivers/hosts with photo, messaging, recognition sign) and Vehicle (kind, energy, plate, rental) entities; structured transport (carrier, number, PNR, from/to with terminal/gate/platform) on items and bookings; memberIds/personIds references and Ticket.memberId; ticket date/time/seat/validUntil and barcode formats pdf417/aztec/ean13/datamatrix; stays: checkin/checkout/breakfastIncluded/rooms; payment (status, deposit, payer) and priceEstimated; member loyalty/dietary/accessibility; 18 new item types (transit, bike, ferry, fuel, event, meeting…). |
1.1 |
2026-08 | Added optional menuUrl (link to a restaurant's menu) on DayItem, ItemOption and Booking; optional outfit (recommended outfit / gear tokens) on DayItem; optional price + currency (ISO 4217) on DayItem and Booking, with a trip-level default currency (absent = EUR), enabling budget aggregation. |
1.0 |
2026-08 | Initial release: trip, members and roles, surprise mode, days and items (16 types), conditional fallbacks, on-site options, bookings, QR / Code 128 tickets with real payloads, vouchers, checklists, contacts, logistics notes, useful apps. |
Proposed changes are discussed before landing in a new release of the specification, the schema and the validator — the three always move together.