OMX Field Mapping

This guide says where the fields of three common entry formats, Hy-Tek semicolon files, RunSignup participants, and Athletic.net entry exports, land in an OMX registration document ("kind": "registration"). Use it if your product already reads or writes one of them. It is a guide, not part of the format: where it and the specification disagree, the specification is right.

Each table was checked against a working importer. A field marked not carried has no OMX home; keep it on your side, keyed by your own id.

Before you map anything: ids

None of these formats carries an id that is guaranteed stable for the life of a meet, and OMX needs one on every record (see Ids in the specification). Mint your own ids when you first read a file, store them with the meet, and reuse them on every later document. Never derive an id from a name: correcting a misspelt name would then change the athlete’s id and break the results join.

A registration number (Hy-Tek field 22, RunSignup registration_id, Athletic.net ANetAthleteId) is a good id when your source keeps it stable. When you know which system issued it, also send it in external_ids under that system’s id (rsu for RunSignup, anet for Athletic.net; the specification’s System ids table lists the keys for systems that write no OMX document), so a Publisher keyed on that system can match the athlete. Hy-Tek is a file format, not a system, so its field 22 alone names no system.

Only the meet, events, teams, and athletes carry external_ids. An entry never does: a Publisher finds a result through its athlete and its event, and a relay through its team, relay letter, and event. So in one document an athlete is entered at most once in an event, and every relay entry carries a letter.

Hy-Tek semicolon entry files

Hy-Tek Meet Manager’s semicolon-delimited entry import has five record types: I (athlete information), D and E (individual entries), Q and R (relays). D and Q carry more than E and R; prefer them.

Fields are numbered from 1 as Hy-Tek’s documentation numbers them, and field 1 is the record type. After splitting a line on ;, field n is at index n − 1: in D;Rivera;Ana;…, field 2 (last name) is Rivera. A record may stop early when its remaining fields are blank. A worked example follows the tables.

Athletes and teams (I, and fields 2 to 10 of D and E)

Individual entries (D, E)

One D or E record is one entry. Hy-Tek has no event list of its own in this file: build events from the distinct event code, gender, and division combinations, and give each a stable id.

Relays (Q, R)

Hy-Tek event codes

Hy-Tek puts the whole event in one code, and so does OMX: most Hy-Tek codes are already OMX codes. Build each OMX event from the code, the athlete’s gender, and the division number on the record.

Running events. The code says what kind of race and how far.

Field events. The code is the event.

Multi-events. Send only the multi-event and its entries, never its component events: Meet Operations builds them, starting from the specification’s default table and following its own rules for the meet. A multi-event may be for any gender in a track meet.

Hy-Tek relay codes

A relay code on a Q or R record is the total distance of the race, sometimes with a letter after it. OMX writes an even relay as legs × each leg, and a medley as its total and R.

Hy-Tek’s 1600 is a relay only on a Q or R record. On a D or E record it is the 1600 m run.

Hy-Tek marks

Field 13 of D and E (field 9 of Q and R) says whether a field mark is metric (M) or English (E). Times are the same either way.

Never convert an English mark to millimetres: send it in inches and let Meet Operations convert, once, if its meet is metric.

A worked example

One athlete with an information record and two entries, the second scratched:

I;Rivera;Ana;J;F;03/14/2009;LHS;Longwood High School;17;11;;;Longwood;FL;;USA;;;;;;LW-2207;214;
D;Rivera;Ana;J;F;03/14/2009;LHS;Longwood High School;17;11;LJ;17-02.50;E;1;214;;D;
D;Rivera;Ana;J;F;03/14/2009;LHS;Longwood High School;17;11;1600;5:21.40;M;1;214;;S;

Field by field: the athlete is Ana J. Rivera, female, born 2009-03-14, age 17, grade 11, from Longwood, FL, USA, on team LHS. Her registration number is LW-2207 and her competitor number, the bib, is 214. Both entries are in division 1. The long jump seed is an English mark, 17 ft 2.5 in. The 1600 m seed is a time, and that entry’s declaration status is S, scratched.

The same records in OMX. Hy-Tek gives a division only as a number, so its name comes from your meet setup:

{
	"divisions": [
		{
			"id": "d-1",
			"name": "Varsity",
			"sequence": 1
		}
	],
	"events": [
		{
			"id": "e-lj-f-1",
			"name": "Varsity Girls Long Jump",
			"code": "LJ",
			"gender": "F",
			"division_id": "d-1"
		},
		{
			"id": "e-1600-f-1",
			"name": "Varsity Girls 1600m",
			"code": "1600",
			"gender": "F",
			"division_id": "d-1"
		}
	],
	"teams": [
		{
			"id": "t-lhs",
			"code": "LHS",
			"name": "Longwood High School"
		}
	],
	"athletes": [
		{
			"id": "LW-2207",
			"first_name": "Ana",
			"middle_name": "J",
			"last_name": "Rivera",
			"gender": "F",
			"age": 17,
			"grade": "11",
			"team_id": "t-lhs",
			"bib": "214",
			"city": "Longwood",
			"region": "FL",
			"country": "US"
		}
	],
	"entries": [
		{
			"id": "n-1",
			"event_id": "e-lj-f-1",
			"athlete_id": "LW-2207",
			"seed": {
				"value": 206.5,
				"unit": "in",
				"display": "17-02.50"
			}
		},
		{
			"id": "n-2",
			"event_id": "e-1600-f-1",
			"athlete_id": "LW-2207",
			"status": "scr",
			"seed": {
				"value": 321400,
				"unit": "ms",
				"display": "5:21.40"
			}
		}
	]
}

• The registration number is the athlete’s id, because this source keeps it stable. If yours does not, mint an id and keep the number in your own records.
• Each event id is made from the code, gender, and division, so the same three always give the same event. Store the ids you mint; never regenerate them.
• The scratched entry stays in the document with status: "scr". Leaving it out would make Meet Operations ask the timer whether to scratch it.
• 17-02.50 is 17 × 12 + 2.5 = 206.5 inches, and 5:21.40 is 321.4 seconds, 321400 ms.

A relay entry names its runners by athlete id, in running order. A Q record gives each runner’s competitor number, so match runners to athletes by bib, and create an athlete for a runner you have not seen:

{
	"id": "n-40",
	"event_id": "e-4x400-f-1",
	"relay": {
		"team_id": "t-lhs",
		"letter": "A",
		"legs": ["LW-2207", "LW-2213", "LW-2219", "LW-2230"]
	},
	"seed": {
		"value": 245200,
		"unit": "ms",
		"display": "4:05.20"
	}
}

RunSignup participants

These are the fields of RunSignup’s race participants API that 2Timer’s connector reads. RunSignup’s own API documentation is the authority for the rest of the response.

The race’s name, next_date, and events (event_id, name, start_time) give meet.name, meet.start_date, and events[]. A start time is not carried. A road race is meet.sport: "run".

A bib in OMX belongs to the athlete. RunSignup gives each registration its own bib, so a runner registered for two races, say Saturday’s 5K and Sunday’s half, has two registrations and two bibs. Send them as two athletes, one per registration, each with its own bib and entry. Award groups RunSignup defines go in groups, and an entry’s group_id names the one RunSignup placed it in when age and gender alone do not decide it.

Athletic.net entry exports

Athletic.net’s meet entry CSV has one row per entry, with the columns below. Athletic.net can also export a Hy-Tek semicolon file; map that as Hy-Tek.

Relay rows carry the team, a relay letter, gender, a total distance (1600 for the 4x400), a seed, and a division, followed by the legs.

Not covered yet

• Hy-Tek .hy3 and other fixed-width files. Only the semicolon format is mapped here.
• MileSplit. No import format is mapped.

If you map one of these, or find a row here that is wrong, send it to [email protected] and it will be added.

This guide is dedicated to the public domain under CC0 1.0.