Event Data File Reference

Event data files let the person preparing TRacer for an event define event, station, race, participant, and entry data before volunteers import it into TRacer. TRacer accepts JSON and YAML event data files.

The official method today is to create this file manually. A community-created builder is available at runner-tracker-json-builder.vercel.app, and a built-in TrackMyRacer.live tool is planned for the future.

File shape

An event data file is one object with event fields and optional arrays for stations, races, participants, and entries.

{
  "name": "Example Trail Run",
  "startDate": "2026-06-12T07:00:00",
  "endDate": "2026-06-12T18:00:00",
  "startStation": 0,
  "finishStation": 11,
  "stations": [],
  "races": [],
  "participants": [],
  "entries": []
}

Event fields

Field	Type	Required	Description
name	string	Recommended	Event name shown in TRacer.
slug	string	Optional	Event slug, if your event uses one.
syncUrl	string	Optional	Sync URL, if your event uses one.
startDate	date/time string	Optional	Event start date or time.
endDate	date/time string	Optional	Event end date or time.
startStation	number	Yes	Station number used as the event start.
finishStation	number	Yes	Station number used as the event finish.

Use date and time strings that JavaScript can read with new Date(...). For event readability, prefer local event-time strings like 2026-06-12T07:00:00 unless you specifically need to include a timezone.

Stations

Use stations to define checkpoint or aid-station locations.

{
  "stations": [
    { "stationNumber": 0, "name": "Start", "distance": 0 },
    { "stationNumber": 2, "name": "Hope Campground", "distance": 5.52 },
    { "stationNumber": 11, "name": "Finish", "distance": 50 }
  ]
}

Field	Type	Required	Description
stationNumber	number	Yes	Number used by TRacer to identify the station.
name	string	Optional	Human-readable station name.
stationNumberDisplayed	string	Optional	Display label shown instead of stationNumber. Useful when a race needs labels like 1A and 1B.
distance	number	Optional	Distance for the station.

Races

Use races when one event has multiple races, or when a race needs station display overrides.

{
  "races": [
    {
      "name": "Out and Back 50K",
      "distance": 31,
      "stations": [
        { "stationNumber": 1, "stationNumberDisplayed": "1A" },
        { "stationNumber": 2 },
        { "stationNumber": 3, "stationNumberDisplayed": "1B" }
      ]
    }
  ]
}

Field	Type	Required	Description
name	string	Yes	Race name.
distance	number	Optional	Race distance.
stations	array	Optional	Station overrides for this race. Each item uses the same public station fields as stations.

Race station entries are overrides from the main station list. For example, if a race passes through the same physical station twice, you can log the second pass under another station number and show display labels such as 1A and 1B.

Participants

Use participants to preload bib numbers and optional participant details.

{
  "participants": [
    { "bibNumber": 101, "firstName": "Sam", "lastName": "Runner", "race": "Out and Back 50K" },
    { "bibNumber": 102, "race": "Out and Back 50K" }
  ]
}

Field	Type	Required	Description
bibNumber	number	Yes	Participant bib number.
firstName	string	Optional	Participant first name.
lastName	string	Optional	Participant last name.
age	string	Optional	Participant age or age range.
gender	M or F	Optional	Participant gender marker.
home	string	Optional	Participant home location.
team	string	Optional	Participant team.
race	string	Optional	Race name for this participant.
note	string	Optional	Additional participant note.
dnfReason	string	Optional	DNF reason, if already known.
dnfStation	number or null	Optional	Station where the participant DNF status applies.
dnfTimestamp	date/time string or null	Optional	Time the DNF was recorded, if known.

Entries

Use entries to preload station timing data.

{
  "entries": [
    { "bibNumber": 101, "stationNumber": 2, "timeIn": "2026-06-12T09:15:00" },
    { "bibNumber": 101, "stationNumber": 2, "timeOut": "2026-06-12T09:20:00" }
  ]
}

Field	Type	Required	Description
bibNumber	number	Yes	Participant bib number.
stationNumber	number	Yes	Station number for the timing entry.
timeIn	date/time string or null	Optional	Time the participant arrived at the station.
timeOut	date/time string or null	Optional	Time the participant left the station.

Internal fields

Do not include internal database fields in manually-created event data files. TRacer handles record IDs, event IDs, and modification timestamps during import.