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
`MINOR` 1.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.
`MAJOR` 1.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.

Reader obligations#

"Player" below means any reader of the format — player, viewer, importer, editor.

#	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.

Compatibility — what claiming Roadbook 1.2 compatibility means#

Any application may implement Roadbook: no registration, API key, certification or permission is required. An application may state that it is "Roadbook 1.2 compatible" (or "Roadbook ≤ 1.2 compatible") when it meets the requirements below for the role(s) it plays. This is a self-declaration; there is no certification process.

Role Minimum requirements

Role	Minimum requirements
`reader` player, viewer, importer	Accepts every valid 1.2 document (the examples are a good test set, demo first). Handles all required fields; degrades gracefully when optional fields are absent. Ignores unknown fields — never rejects a file because of them — and preserves them when it rewrites the file. Does not reject additive extensions: a 1.3 file with the same major version opens, surfacing that some fields may not be displayed. Renders tickets from `payload` + `format` if it claims ticket support.
`writer` generator, exporter, converter, AI tool	Generates documents valid against the JSON Schema and the integrity rules (zero errors from the reference validator). Declares the `formatVersion` matching the fields it actually emits. Uses the documented conventions: ISO dates, `HH:MM` local times, English enum tokens, unique ids, resolving references. Keeps media out of band (URLs or relative paths), never inline binaries. Prefixes vendor extensions (`x-myapp-…`).

reader
player, viewer, importer

Accepts every valid 1.2 document (the examples are a good test set, demo first).
Handles all required fields; degrades gracefully when optional fields are absent.
Ignores unknown fields — never rejects a file because of them — and preserves them when it rewrites the file.
Does not reject additive extensions: a 1.3 file with the same major version opens, surfacing that some fields may not be displayed.
Renders tickets from payload + format if it claims ticket support.

writer
generator, exporter, converter, AI tool

Generates documents valid against the JSON Schema and the integrity rules (zero errors from the reference validator).
Declares the formatVersion matching the fields it actually emits.
Uses the documented conventions: ISO dates, HH:MM local times, English enum tokens, unique ids, resolving references.
Keeps media out of band (URLs or relative paths), never inline binaries.
Prefixes vendor extensions (x-myapp-…).

Suggested wording for documentation, store listings or an "about" screen: Roadbook 1.2 compatible · Reads Roadbook ≤ 1.2 · Exports Roadbook 1.2. No badge image is provided for now; plain text is enough. Listed implementations: viewers & players; to be listed, submit yours.

History#

Summary — the changelog has the detailed list of additions, deprecations and compatibility notes per release.

Version	Date	Changes
`1.2`	2026-08-08 amended to 2026-08-22	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…). Added 2026-08 (still 1.2, optional): root `brand` (distributor branding with an Ed25519 `signature` binding the roadbook id to the brand; unlicensed players ignore the theme).
`1.1`	2026-08-07	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-04	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.