OpenRoadBook logo

Format overview

This OpenRoadBook standard establishes a file layout, core fields, and symbol registry to be used for roadbooks. The current release targets adventure and non-competitive events; profiles provide a path to other disciplines without changing the base structure.

Data model Symbol registry

Purpose

Provide a single, unambiguous file format for describing stages and navigation instructions so authors and tools can interoperate. The format emphasises explicit units, stable symbol IDs, and a small set of well-defined fields.

  • Single source of truth for printed roadbooks, GPS exports, and digital renderers.
  • Readable by humans (YAML) and consumable by machines (JSON/validation).
  • Profiles and extensions for different assurance levels without breaking existing files.

Data model

The data model describes an ordered sequence of entries (instructions) with well-typed fields. Authors supply distances, symbol references (tulips), headings (CAP), notes, and optional coordinates or metadata used by renderers and converters.

Entry fields

  • km · cumulative distance (float, kilometers)
  • tulip · symbolic ID for navigation diagram
  • cap · heading 0–359 (integer)
  • notes · free text instructions
  • symbols · array of registry IDs
  • waypoint · optional GPS coordinate pair
  • speed_limit · optional integer in km/h

Profiles & extensions

Profiles tailor the schema to different environments while preserving compatibility. Unknown fields are preserved for forward compatibility.

  • FIA profile: sticks to Appendix II requirements.
  • Adventure profile: adds tip and landmark text.
  • Custom profiles: append domain-specific metadata via extensions.

Sample entry

meta:
  format: OpenRoadBook
  version: 1.0
  event:
    name: Rally of Exampleland
    stage: SS1

entries:


    

  • km: 12.35
tulip: turn_left
cap: 270
notes: “Gravel, caution rocks”
symbols: [danger2, jump]
waypoint: { lat: 41.12345, lon: 2.12345 }

Symbol registry

The registry maps short IDs to pictograms, categories, and descriptions. Tools should use these IDs for rendering and validation. New symbols append to the registry; existing IDs are never reused.

Navigation / Direction

Core tulips such as start, finish, turn_left, roundabout.

Hazards

Graduated warnings: danger1, danger2, danger3, plus jump, ford, cliff.

Road & surface

Surface cues such as tarmac, gravel, sand, offtrack, gate.

Services & controls

Logistics touchpoints: fuel, service, speed_limit, neutralization, cp, wp.

Adventure extensions

Optional IDs like camp, water, food, scenic, border, and town enrich overland journeys.

Registry file

Symbol metadata ships in YAML: ID, display name, category, SVG filename, and description.

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

Implementation roadmap

Focus areas that help the community publish and adopt the format. Track progress in the public roadmap or spin up working groups for your specialty.

Open symbol registry

  • Commission or crowdsource clean-room SVGs.
  • Release assets under permissive licenses (CC0/CC-BY).
  • Host registry YAML + artwork in a public repository.

Schema validation

  • Publish JSON Schema to validate YAML/JSON inputs.
  • Ensure fields use correct types and registry IDs.
  • Automate checks in CI before releasing roadbooks.

Reference converters

  • Produce FIA-style PDF output from OpenRoadBook entries.
  • Ship GPX/KML converters for GPS devices.
  • Demonstrate digital dash integrations.

Governance & versioning

  • Adopt semantic versioning for schema and registry.
  • Publish release notes and changelogs transparently.
  • Form a working group of organizers, developers, riders.

Documentation & examples

  • Maintain the specification and quick-start guides.
  • Share sample YAML roadbooks with rendered PDFs.
  • Highlight community toolchains (CORBS, editors, viewers).

What’s next?

Format overview · Last updated 29 Oct 2025

Continue to the specification

Work through the demo

Download the Montseny i Guilleries sample ORB file, validate it against the published schema, and use it as a template for your own stages.

Open the demo walkthrough Download the ORB file View the schema