rdbk · v1.0application/x-roadbook.rdbk

The .rdbk standard

An open format for digital roadbooks, packaged as a ZIP container. A self-contained UTF-8 roadbook.json carries the whole route — track, notes, headings, junction diagrams and its own symbols — alongside optional photos and voice notes, so a roadbook is just a file you can read, follow, share and archive.

Why .rdbk

• Self-contained. A .rdbk embeds the symbols it uses (as data URIs), so it renders identically anywhere — offline, years later — with no external icon packs to lose.
• Plain JSON inside. Open roadbook.json in any text editor, parse it with one line in any language, diff it in git.
• Map-ready. The full GPS track travels with the notes, so any reader can draw the route and place you on it.
• Symbols are first-class. Each note can carry positioned, rotated, scalable pictograms and colored junction vectors — not just a line of text.

Container (the file)

A .rdbk file is a ZIP container. Inside it, roadbook.json holds the roadbook — the schema described below, with symbols still embedded in its icons — alongside optional bundled media:

my-roadbook.rdbk   (ZIP)
├─ roadbook.json     // the roadbook — schema below
├─ media.json        // optional — geotags for the bundled media
├─ photos/…          // optional — geotagged photos
└─ audio/…           // optional — voice notes

Photos and voice notes are optional: they travel only when the exporter includes them. The file's MIME type stays application/x-roadbook.

Document structure

roadbook.json is a single JSON object with four top-level keys:

{
  "meta":  { … },   // document metadata
  "track": [ … ],   // the GPS polyline (ordered points)
  "notes": [ … ],   // navigation notes, ordered along the track
  "icons": { … }    // embedded symbol library (name → data URI)
}

Coordinates are WGS-84 decimal degrees. Distances are integer metres. Headings are degrees clockwise from true north (0–360). Symbol angles are degrees clockwise.

meta

track

An ordered array of points describing the route polyline. Notes reference into it by index. Each point may carry an optional ele — the elevation in integer metres — and an optional t — the fix time in epoch milliseconds (UTC), kept from a recording so tools can order or time-match points.

"track": [
  { "lat": 45.82712, "lon": 9.41164, "ele": 1245, "t": 1783065600000 },
  { "lat": 45.82740, "lon": 9.41180 }
]

notes

The heart of a roadbook: an ordered list of waypoints, each with an instruction, heading and symbols. A reader highlights the active note and validates progress against the GPS track.

{
  "num": 12, "idx": 184,
  "lat": 45.8321, "lon": 9.4002,
  "distance": 8420, "partial_distance": 630,
  "text": "Bear right onto the gravel track",
  "cap": 247, "cap_distance": 300, "cap_type": "average",
  "bearing_in": 92, "bearing_out": 247,
  "road_type_in": 2, "road_type_out": 3,
  "speed_limit": 30,
  "danger": 2,
  "icons": [
    { "name": "S03_30km.svg", "pos": [40, 22], "angle": 0, "size": 32, "flip_x": false }
  ],
  "junctions": [
    { "pivot": [0, 0], "tip": [45, 25], "width": 3, "road_type": 3 }
  ]
}

A comment note (note_kind: "comment") is coordinate-less — it holds only its text and an optional embedded image:

{
  "note_kind": "comment",
  "text": "Presented by ACME Rally Gear",
  "image": "data:image/png;base64,iVBORw0KGgo…"
}

Symbols (note icons + top-level icons library)

A note's icons array places pictograms on a fixed 230 × 162 reference box. The origin is the box centre; +y points up. This makes a note render the same at any display size.

The symbols themselves live inside the file in icons, a map from symbol name to a data URI. This is what makes a .rdbk portable: every symbol it draws is embedded.

"icons": {
  "S03_30km.svg": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0i…",
  "P07_ponte.png": "data:image/png;base64,iVBORw0KGgoAAAANS…"
}

Resolution order for a symbol: an inline data: URI on the icon → the file's icons (case-insensitive) → a host symbol set. A note may also carry a speed limit encoded in a symbol name (e.g. S03_30km ⇒ 30 km/h; S99_end clears it).

Road types

A note's vignette is a tulip: the road you arrive from always enters from the bottom edge to the box centre (drawn per road_type_in), the road you leave on exits from the centre to an arrow at the top (per road_type_out), and junction vectors branch from the centre. Stroke width is indicative of the road type.

Junction vectors (junctions)

Beyond text, a note can draw the junction itself: one or more vectors on the same 230 × 162 box. Each goes from a pivot to a tip (arrow head), colored by road type and drawn with a stroke width.

"junctions": [
  { "pivot": [0, 0], "tip": [45, 25], "width": 3, "road_type": 3 },
  { "pivot": [0, 0], "tip": [-30, 40], "width": 2, "road_type": 4 }
]

Result token (optional, for events)

When a roadbook is followed competitively, a reader can emit a compact, fixed-width 49-character result token (suitable for a QR code). It is a sequence of zero-padded numeric fields and carries no personal data:

The token may be appended with -<sig>, a truncated HMAC over the token, for tamper-evidence between the reader and the scorer.

Conformance

• A .rdbk is a ZIP container with a UTF-8 roadbook.json inside; extension .rdbk, media type application/x-roadbook.
• A conforming reader MUST read roadbook.json from the container, render track and notes in order and resolve symbols from icons first.
• A conforming writer MUST embed every symbol referenced by any note into icons, so roadbook.json is self-contained.
• Unknown fields MUST be preserved on round-trip and ignored if not understood (forward-compatibility).
• A conforming reader MUST render notes with note_kind: "comment" in the roadbook list but MUST NOT number them, place them on the map, score them or emit them as GPX/KMZ waypoints.

Full minimal example

{
  "meta": { "title": "Demo loop", "total_distance": 1210, "note_count": 2,
            "author": "Alex Driver", "organization": "Rally Club", "modified": "2026-06-09",
            "logo": "data:image/png;base64,iVBORw0KGgo…" },
  "track": [
    { "lat": 45.8271, "lon": 9.4116 },
    { "lat": 45.8290, "lon": 9.4135 },
    { "lat": 45.8305, "lon": 9.4150 }
  ],
  "notes": [
    {
      "num": 1, "idx": 0, "lat": 45.8271, "lon": 9.4116,
      "distance": 0, "partial_distance": 0, "text": "Start",
      "cap": null, "cap_distance": null, "bearing_in": 0, "bearing_out": 45,
      "road_type_in": 3, "road_type_out": 3, "icons": [], "junctions": null
    },
    {
      "num": 2, "idx": 2, "lat": 45.8305, "lon": 9.4150,
      "distance": 1210, "partial_distance": 1210, "text": "Finish",
      "cap": null, "cap_distance": null, "bearing_in": 45, "bearing_out": 0,
      "road_type_in": 3, "road_type_out": 3,
      "icons": [ { "name": "i01_arrivo.png", "pos": [0, 0], "angle": 0, "size": 40, "flip_x": false } ],
      "junctions": null
    }
  ],
  "icons": { "i01_arrivo.png": "data:image/png;base64,iVBORw0KGgoAAAANS…" }
}

Open a .rdbk in the Reader