OpenRoadBook specification v1.0 (Draft)

1. Introduction

1.1 Purpose

OpenRoadBook defines an open, human‑friendly, machine‑readable format for roadbooks. It is designed for both competitive rally events (FIA‑style) and non‑competitive adventure travel (motorbike, 4x4, overland). It enables interoperability between peers, organizers, competitors, and software tools, while remaining easy to author and validate.

1.2 Goals

• Provide a standardized schema for roadbook data.
• Ensure human readability (YAML as canonical format).
• Support machine validation and conversion into FIA‑style PDFs, GPX/KML, and digital formats.
• Define a stable symbol registry aligned with FIA pictograms.
• Enable extensibility without breaking compatibility.

2. Scope

This specification applies to:

• Organized competition (where FIA compliance is required).
• Independent adventure navigation (where GPS may be unavailable or undesired).

It covers:

• Event metadata.
• Roadbook entries (distances, tulips, notes, symbols).
• Symbol definitions for navigation, hazards, services, and adventure travel.

It does not prescribe:

• Exact rendering (fonts, layouts).
• Proprietary extensions beyond the defined schema.

3. Terminology

• Entry: A single row in a roadbook, typically containing a tulip diagram, distance, and notes.
• Tulip: A symbolic representation of a navigation instruction.
• Symbol: A standardized pictogram representing hazards, services, or controls.
• Registry: The authoritative list of symbol IDs and metadata.
• Profile: A defined subset or extension of the specification for a particular use case (e.g., FIA, Adventure).

GPS fields (waypoint) are optional. Roadbooks may be fully usable without GPS coordinates, relying solely on distances, tulips, and notes.

4. Data Model

4.1 File Format

• Canonical authoring format: YAML 1.2.
• Alternative representations, such as JSON or XML, are not supported; tools and authors MUST use YAML as the canonical format.
• Files must declare meta.format: OpenRoadBook and meta.version.

4.2 Structure Example

meta:
  format: OpenRoadBook
  version: 1.0
  event:
    name: Rally of Exampleland
    date: 2025-10-23
    stage: SS1
    organizer: Example Rally Club
    regulations: FIA Cross-Country Rally Appendix II

entries:
  - km: 0.00
    tulip: start
    cap: 90
    notes: "Start of stage"
    symbols: [start]
    waypoint: { lat: 41.12345, lon: 2.12345 }

  - km: 12.35
    tulip: turn_left
    cap: 270
    notes: "Gravel, caution rocks"
    symbols: [danger2, jump]
    speed_limit: 50

4.3 Field Definitions

• km: cumulative distance (float, km).
• tulip: symbolic ID for tulip diagram.
• cap: compass heading (0–359).
• notes: free text.
• symbols: array of symbol IDs from the registry.
• speed_limit: optional integer (km/h).
• waypoint: optional {lat, lon} object.
• tip (Adventure profile): optional free text with practical advice.
• landmark (Adventure profile): optional free text describing a visible landmark.

5. Symbol Registry

5.1 Purpose

The registry defines a stable vocabulary of symbol IDs. Each ID maps to metadata and an SVG/PNG asset.

5.2 Example Entry

symbols:
  - id: danger2
    name: "Danger (2 exclamations)"
    category: hazard
    svg: danger2.svg
    description: "Serious hazard, reduce speed"

5.3 Core Categories

• Navigation: start, finish, turn_left, turn_right, straight, roundabout, junction
• Hazards: danger1, danger2, danger3, jump, ford, bridge, railroad, cliff, rocks, animals
• Road/Surface: tarmac, gravel, sand, offtrack, fence, gate
• Services/Controls: fuel, service, speed_limit, neutralization, cp, wp

5.4 Adventure Extensions

• camp — campsite
• water — potable water source
• food — restaurant or supply point
• scenic — viewpoint / landmark
• border — border crossing / checkpoint
• town — settlement / village

6. Validation

• A JSON Schema (or equivalent) must be published to validate OpenRoadBook files.
• Validation ensures:
  • km is numeric.
  • cap is 0–359.
  • symbols reference valid IDs.
  • Required fields are present.
• The draft adventure schema is available at https://openroadbook.com/schemas/orb.schema.json (JSON Schema Draft 2020-12). Versioned snapshots live under https://openroadbook.com/schemas/1.0/orb.schema.json, https://openroadbook.com/schemas/1.1/orb.schema.json, etc., so tools can pin to a specific release.

7. Interoperability

• Tools must support import/export of YAML and JSON.
• Converters may generate:
  • PDF (FIA‑style layout).
  • GPX/KML (for GPS devices).
  • Digital roadbook formats (RBK‑like).

8. Versioning

• Semantic versioning: MAJOR.MINOR.
• Breaking changes increment MAJOR.
• Additive changes (new fields, new symbols) increment MINOR.

9. Governance

• OpenRoadBook is community‑driven.
• Changes are proposed via public discussion (e.g., GitHub issues).
• A working group of organizers, developers, and competitors approves updates.

10. Compliance

A tool is OpenRoadBook‑compliant if it:

1. Can parse and validate OpenRoadBook v1 YAML.
2. Can render or export roadbooks using the official symbol registry.
3. Preserves unknown fields (for forward compatibility).

Profiles

FIA Profile

• Must use only FIA‑recognized symbols.
• Must comply with FIA formatting rules.
• Intended for competitive events.

Adventure Profile

• May use extended symbols (Appendix B).
• May include optional fields like tip: or landmark: for descriptive guidance.
• Intended for non‑competitive navigation.

Appendix A: Example Roadbook Entry

- km: 25.40
  tulip: turn_right
  cap: 180
  notes: "Sharp right, rocks inside"
  symbols: [danger2, rocks]
  waypoint: { lat: 41.67890, lon: 2.67890 }

Appendix B: Adventure extensions

B.1 Additional Symbols

• camp — campsite
• water — potable water source
• food — restaurant or supply point
• scenic — viewpoint / landmark
• border — border crossing / checkpoint
• town — settlement / village

B.2 Optional Fields

• tip: free text with practical advice (e.g., “Good place to refuel body and bike”).
• landmark: free text describing a visible landmark (e.g., “Look for the old stone bridge”).

B.3 Example

- km: 45.20
  tulip: straight
  notes: "Pass through small village, bakery on right"
  symbols: [town, food]
  tip: "Good place to refuel body and bike"

title: “Specification” description: “Normative guidance for the OpenRoadBook adventure release, with a roadmap toward FIA-compliant, professional rally workflows.”