SwimJSON

An open format for swim meet data

SwimJSON is a proposed open standard for swim meet data: a common way for meet directors, timing systems and software developers to exchange events, entries, results and the timing readings behind them.

Today most of that data moves in formats that only particular software can read or write. An open format makes meet data portable, easier to check, and easier to build on, without depending on any one vendor.

Example swim meet data in each format

Let's use a fictional meet. Maya Chen, 14, swims the girls 13-14 100 free prelims in heat 4, lane 4, and touches in 1:02.88. This is what the file knows about that swim.

Girls 13-14 100 Yard Freestyle · Preliminaries · short course yards
Maya ChenSalish Sea Swim Team
Cascade Spring Invitational · April 11, 2026
Heat, lane
Heat 4 · Lane 4
Official time
1:02.88 · 3rd in the age group
Readings
Pad 1:02.88official
Buttons A 1:02.91 · B 1:02.85 · C 1:02.90
Watch 1:02.97
Reaction, splits
+0.71 · 14.62 / 30.41 / 46.60 / 1:02.88
Source
Colorado Time Systems System 6 v3.2 · race file 001-003-004P0031

The file a meet produces depends mostly on where it is held. In the United States most results move as Hy‑Tek HY3 and CL2 files, and many European federations use Lenex.

United States

HY3 and SwimJSON comparison

Hy‑Tek HY3Proprietary

Fixed-width records. Each value lives at a set column position.

        10        20        30        40        50        60        70        80        90       100       110       120       130
.........|.........|.........|.........|.........|.........|.........|.........|.........|.........|.........|.........|.........|
E1F    1Chen FG   100A 13 14  0A  0.00  3       NTY   63.10Y    0.00    0.00   NN               N                               88
E2P   62.88Y          4  4  1   3      62.91   62.85   62.90        62.88     0.00 0.7104112026                                 86
G1P 1   14.62P 2   30.41P 3   46.60P 4   62.88                                                                                  74
official time pad and button readings reaction time and splits where it came from
What you're looking at
  • Three lines of a 24-line file: E1 is the entry, E2 the result, G1 the splits. Each line is 130 characters wide, and the two digits at the end are a checksum.
  • The pad time and the three button times are present. When the official time is not the pad's, the file does not say how it was found.
  • The swimmer appears as the first five letters of the last name. The full name is on a separate D1 line elsewhere in the file.
  • The layout has not been published, so a program that reads it works from a reconstruction.
SwimJSONOpen format

The same swim as a JSON object, in excerpt.

{  "officialTime": "1:02.88",  "timing": {    "primary": "1:02.88",    "secondary": {      "A": "1:02.91",      "B": "1:02.85",      "C": "1:02.90"    },    "tertiary": {      "A": "1:02.97"    }  },  "reactionTime": "+0.71",  "splits": [    {"distance": 25, "cumulative": "14.62"},    {"distance": 50, "cumulative": "30.41"},    {"distance": 75, "cumulative": "46.60"},    {"distance": 100, "cumulative": "1:02.88"}  ],  "provenance": {    "sourceId": "src-console",    "record": "001-003-004P0031"  }}
Show the complete result object
{  "id": "x-1p",  "eventId": "ev-3",  "round": "PRE",  "athleteId": "a-1",  "entryId": "n-1",  "heatId": "h-3p-4",  "lane": 4,  "date": "2026-04-11",  "officialTime": "1:02.88",  "course": "SCY",  "status": "VALID",  "place": 3,  "heatPlace": 1,  "timing": {    "primary": "1:02.88",    "secondary": {      "A": "1:02.91",      "B": "1:02.85",      "C": "1:02.90"    },    "tertiary": {      "A": "1:02.97"    },    "raw": {      "race": "001-003-004P0031"    }  },  "reactionTime": "+0.71",  "splits": [    {"distance": 25, "cumulative": "14.62"},    {"distance": 50, "cumulative": "30.41", "lap": "15.79"},    {"distance": 75, "cumulative": "46.60", "lap": "16.19"},    {"distance": 100, "cumulative": "1:02.88", "lap": "16.28"}  ],  "timeStandardsMet": ["ts-pn-champs-2026-f-13-14"],  "provenance": {    "sourceId": "src-console",    "record": "001-003-004P0031"  }}
Same swim, more of it
  • The values have names, so a person can read them and a program can check them against the schema.
  • The meet lists its timing systems once, as the rulebook names them: primary, the touchpads; secondary, three buttons; tertiary, one watch. Each reading is filed under its system, and buttons keep their letters.
  • The console and race file the values came from are recorded.

SDIF and CL2

USA Swimming's SDIF (.sd3) was specified in 1998, and Hy‑Tek's CL2 uses the same record layout with a checksum added to each line. Meet Manager's results export is a zip holding a CL2 file and an HY3 file, and an SD3 file comes from a separate conversion step. USA Swimming's times manual names SDIF, CL2, XDIF and HY3 as electronic results files. Here is Maya's event as an SDIF record, which holds her prelim and her final together.

USA Swimming SDIFPublished, 1998

One D0 record, 160 columns, laid out from the SDIF version 3 specification.

        10        20        30        40        50        60        70        80        90       100       110       120       130       140       150       160
.........|.........|.........|.........|.........|.........|.........|.........|.........|.........|.........|.........|.........|.........|.........|.........|
D01        Chen, Maya                  PN2C7K41M   A   0203201214FF 10013   131404112026 1:03.10Y 1:02.88Y          1:02.40Y 4 4 1 5  3  2                      
prelim time final time
What the file keepsHY3SDIFLenexSwimJSON
The official timeyesyesyesyes
What the pad and the buttons readyesnonoyes
How the official time was determinednononoyes
Reaction time and splitsyessplits, in another recordyesyes
Which console and race file it came fromnononoyes
A meet's own custom datanonofederation extensions, added to the document by its maintaineryes
A published layoutnoyes, 1998yesyes
A machine-readable schemanononoyes
A way to check a filenonoa basic upload check from its maintainera validator you can run: structure, then relationships
Who maintains itHy‑Tek (Active)USA Swimmingone maintaineran open process

When the pad misses

In the same heat, Ava Nguyen touches too softly in lane 5. The pad stops at 1:05.37, more than a second behind the buttons, and button B records nothing. Under USA Swimming rule 102.23.4, her official time is the average of buttons A and C with the thousandths dropped: 1:04.195 becomes 1:04.19.

Hy‑Tek HY3Proprietary

Ava's entry and result lines.

        10        20        30        40        50        60        70        80        90       100       110       120       130
.........|.........|.........|.........|.........|.........|.........|.........|.........|.........|.........|.........|.........|
E1F    6NguyeFG   100A 13 14  0A  0.00  3       NTY   64.60Y    0.00    0.00   NN               N                               59
E2P   64.19Y          4  5  2   7      64.17    0.00   64.22        65.37     0.00     04112026                                 95
official time button and pad readings
What you're looking at
  • The official time, 64.19, matches neither the pad nor either button.
  • Button B reads 0.00 in its own column, so A and C stay in theirs.
  • Nothing on the line says how 64.19 was found.
SwimJSONOpen format

The official time, the readings, and how one came from the others.

{  "officialTime": "1:04.19",  "timing": {    "primary": "1:05.37",    "secondary": {      "A": "1:04.17",      "C": "1:04.22"    },    "tertiary": {      "A": "1:04.25"    },    "determination": {      "from": "SECONDARY",      "rule": "AVERAGE"    }  }}
Show the complete result object
{  "id": "x-4",  "eventId": "ev-3",  "round": "PRE",  "athleteId": "a-6",  "entryId": "n-4",  "heatId": "h-3p-4",  "lane": 5,  "date": "2026-04-11",  "officialTime": "1:04.19",  "course": "SCY",  "status": "VALID",  "place": 7,  "heatPlace": 2,  "timing": {    "primary": "1:05.37",    "secondary": {      "A": "1:04.17",      "C": "1:04.22"    },    "tertiary": {      "A": "1:04.25"    },    "determination": {      "from": "SECONDARY",      "rule": "AVERAGE"    }  },  "provenance": {    "sourceId": "src-console",    "record": "001-003-004P0031"  }}
Same swim, more of it
  • determination says the time came from the secondary system, the buttons, by the rule for two valid times. It appears only when the official time is not the pad's.
  • Button B is missing from the readings, so it is plain which one recorded nothing.
  • The validator checks the arithmetic. A file that gave 1:04.20, the rounded average, would fail.

A relay

Cascade Aquatic Club's A relay wins the mixed 13-14 200 medley relay in 1:58.73: Emma Johansson on backstroke, Lucas Ortiz on breaststroke, Noah Patel on butterfly and Ava Nguyen on freestyle.

Hy‑Tek HY3Proprietary

The relay's entry, result, splits and legs.

        10        20        30        40        50        60        70        80        90       100       110       120       130
.........|.........|.........|.........|.........|.........|.........|.........|.........|.........|.........|.........|.........|
F1CAC  A  13XXX   200E 13 14  0S  0.00 12       NTY  121.50Y    0.00    0.00   NN   4           N                               98
F2F  118.73Y          2  3  0   1     118.80  118.76  118.79       118.73     0.00 0.70 0.21 0.04 0.1504112026                  78
G1F 2   32.10F 4   65.95F 6   93.35F 8  118.73                                                                                  54
F3F    2JohanF1M    3OrtizF2M    4PatelF3F    6NguyeF4                                                                          53
official time the legs and their take-offs splits
What you're looking at
  • F1 is the relay entry, F2 the result, G1 the splits and F3 the legs.
  • F2 holds the lead-off's reaction time and then each later swimmer's take-off, without signs.
  • F3 names each swimmer by the first five letters of the last name, with the leg number.
SwimJSONOpen format

The same relay swim, in excerpt.

{  "officialTime": "1:58.73",  "relayLegs": [    {"position": 1, "athleteId": "a-2", "legTime": "32.10", "takeoff": "+0.70"},    {"position": 2, "athleteId": "a-3", "legTime": "33.85", "takeoff": "+0.21"},    {"position": 3, "athleteId": "a-4", "legTime": "27.40", "takeoff": "+0.04"},    {"position": 4, "athleteId": "a-6", "legTime": "25.38", "takeoff": "+0.15"}  ],  "splits": [    {"distance": 50, "cumulative": "32.10"},    {"distance": 100, "cumulative": "1:05.95"},    {"distance": 150, "cumulative": "1:33.35"},    {"distance": 200, "cumulative": "1:58.73"}  ]}
Show the complete result object
{  "id": "x-2",  "eventId": "ev-12",  "round": "TIM",  "relayId": "r-CASM-A-ev-12",  "entryId": "n-2",  "heatId": "h-12-2",  "lane": 3,  "date": "2026-04-11",  "officialTime": "1:58.73",  "course": "SCY",  "status": "VALID",  "place": 1,  "points": 18,  "timing": {    "primary": "1:58.73",    "secondary": {      "A": "1:58.80",      "B": "1:58.76",      "C": "1:58.79"    }  },  "relayLegs": [    {      "position": 1,      "athleteId": "a-2",      "legTime": "32.10",      "takeoff": "+0.70",      "status": "VALID"    },    {      "position": 2,      "athleteId": "a-3",      "legTime": "33.85",      "takeoff": "+0.21",      "status": "VALID"    },    {      "position": 3,      "athleteId": "a-4",      "legTime": "27.40",      "takeoff": "+0.04",      "status": "VALID"    },    {      "position": 4,      "athleteId": "a-6",      "legTime": "25.38",      "takeoff": "+0.15",      "status": "VALID"    }  ],  "splits": [    {"distance": 50, "cumulative": "32.10"},    {"distance": 100, "cumulative": "1:05.95"},    {"distance": 150, "cumulative": "1:33.35"},    {"distance": 200, "cumulative": "1:58.73"}  ]}
Same swim, more of it
  • Each leg names its swimmer by id, which points to the full athlete record, and carries the leg's own time.
  • On leg 1 the take-off is the reaction time. On later legs it is the exchange margin, negative when a swimmer leaves early.

A meet's own event

SwimJSON can also carry what a meet invents for itself. Say Cascade Aquatic Club closes its invitational with a relay where each swimmer keeps an inflatable pink flamingo on their head. In the file it is an ordinary event, and the club's own fields ride along under the club's own name, so the tradition can be tracked from year to year. Software that doesn't know those fields skips them.

SwimJSONOpen format

The event object. HY3 has no place for the club's fields.

{  "id": "ev-30",  "number": 30,  "sessionId": "s2",  "name": "Mixed 13-14 200 Yard Flamingo Freestyle Relay",  "sex": "X",  "distance": 50,  "stroke": "FREE",  "relayCount": 4,  "course": "SCY",  "eventType": "EXHIBITION",  "ageGroups": [    {      "min": 13,      "max": 14,      "calc": "SINGLE",      "label": "13-14",      "id": "ag-30-13-14"    }  ],  "rounds": [    {"round": "TIM", "heats": [{"id": "h-30-1", "number": 1, "status": "OFFICIAL"}]}  ],  "status": "OFFICIAL",  "ext": {    "cac": {      "tradition": "Flamingo Relay",      "since": 2023,      "rule": "Each swimmer keeps an inflatable pink flamingo on their head for the whole leg. A dropped flamingo adds five seconds.",      "trophy": "The Golden Flamingo, held by the winning club until next year's meet"    }  }}
the club's own fields

Europe

Lenex and SwimJSON comparison

Lenex is an open XML format. It is the recommended format for the European Aquatics rankings, and its documentation was last revised in March 2025. Here is Maya's prelim in Lenex, and what two common converters make of it.

Lenex 3.0Open format

Laid out from the Lenex 3.0 documentation, with the required attributes and a few more.

<?xml version="1.0" encoding="UTF-8"?><LENEX version="3.0">  <CONSTRUCTOR name="swimjson.org example" version="0.1">    <CONTACT email="example@swimjson.org" />  </CONSTRUCTOR>  <MEETS>    <MEET name="Cascade Spring Invitational" city="Everett" nation="USA" course="SCY">      <SESSIONS>        <SESSION number="1" date="2026-04-11">          <EVENTS>            <EVENT eventid="1" number="3" gender="F" round="PRE">              <SWIMSTYLE distance="100" relaycount="1" stroke="FREE" />              <AGEGROUPS>                <AGEGROUP agegroupid="1" agemin="13" agemax="14">                  <RANKINGS>                    <RANKING place="3" resultid="1" />                  </RANKINGS>                </AGEGROUP>              </AGEGROUPS>              <HEATS>                <HEAT heatid="1" number="4" />              </HEATS>            </EVENT>          </EVENTS>        </SESSION>      </SESSIONS>      <CLUBS>        <CLUB name="Salish Sea Swim Team">          <ATHLETES>            <ATHLETE athleteid="1" lastname="Chen" firstname="Maya" gender="F" birthdate="2012-02-03">              <RESULTS>                <RESULT resultid="1" eventid="1" heatid="1" lane="4" swimtime="00:01:02.88" reactiontime="+71">                  <SPLITS>                    <SPLIT distance="25" swimtime="00:00:14.62" />                    <SPLIT distance="50" swimtime="00:00:30.41" />                    <SPLIT distance="75" swimtime="00:00:46.60" />                  </SPLITS>                </RESULT>              </RESULTS>            </ATHLETE>          </ATHLETES>        </CLUB>      </CLUBS>    </MEET>  </MEETS></LENEX>
swim time reaction time and splits the place
xmltodict 1.0.4

A popular Python library that turns XML into JSON.

{  "LENEX": {    "MEETS": {      "MEET": {        "CLUBS": {          "CLUB": {            "ATHLETES": {              "ATHLETE": {                "RESULTS": {                  "RESULT": {                    "@lane": "4",                    "@swimtime": "00:01:02.88",                    "@reactiontime": "+71",                    "SPLITS": {                      "SPLIT": [                        {"@distance": "25", "@swimtime": "00:00:14.62"},                        {"@distance": "50", "@swimtime": "00:00:30.41"},                        {"@distance": "75", "@swimtime": "00:00:46.60"}                      ]                    }                  }                }              }            }          }        }      }    }  }}
Show the complete output
{  "LENEX": {    "@version": "3.0",    "CONSTRUCTOR": {      "@name": "swimjson.org example",      "@version": "0.1",      "CONTACT": {        "@email": "example@swimjson.org"      }    },    "MEETS": {      "MEET": {        "@name": "Cascade Spring Invitational",        "@city": "Everett",        "@nation": "USA",        "@course": "SCY",        "SESSIONS": {          "SESSION": {            "@number": "1",            "@date": "2026-04-11",            "EVENTS": {              "EVENT": {                "@eventid": "1",                "@number": "3",                "@gender": "F",                "@round": "PRE",                "SWIMSTYLE": {                  "@distance": "100",                  "@relaycount": "1",                  "@stroke": "FREE"                },                "AGEGROUPS": {                  "AGEGROUP": {                    "@agegroupid": "1",                    "@agemin": "13",                    "@agemax": "14",                    "RANKINGS": {                      "RANKING": {                        "@place": "3",                        "@resultid": "1"                      }                    }                  }                },                "HEATS": {                  "HEAT": {                    "@heatid": "1",                    "@number": "4"                  }                }              }            }          }        },        "CLUBS": {          "CLUB": {            "@name": "Salish Sea Swim Team",            "ATHLETES": {              "ATHLETE": {                "@athleteid": "1",                "@lastname": "Chen",                "@firstname": "Maya",                "@gender": "F",                "@birthdate": "2012-02-03",                "RESULTS": {                  "RESULT": {                    "@resultid": "1",                    "@eventid": "1",                    "@heatid": "1",                    "@lane": "4",                    "@swimtime": "00:01:02.88",                    "@reactiontime": "+71",                    "SPLITS": {                      "SPLIT": [                        {"@distance": "25", "@swimtime": "00:00:14.62"},                        {"@distance": "50", "@swimtime": "00:00:30.41"},                        {"@distance": "75", "@swimtime": "00:00:46.60"}                      ]                    }                  }                }              }            }          }        }      }    }  }}
fast-xml-parser 5.11.2

A popular JavaScript library that turns XML into JSON.

{"?xml": "", "LENEX": {"CONSTRUCTOR": {"CONTACT": ""}, "MEETS": {"MEET": {"SESSIONS": {"SESSION": {"EVENTS": {"EVENT": {"SWIMSTYLE": "", "AGEGROUPS": {"AGEGROUP": {"RANKINGS": {"RANKING": ""}}}, "HEATS": {"HEAT": ""}}}}}, "CLUBS": {"CLUB": {"ATHLETES": {"ATHLETE": {"RESULTS": {"RESULT": {"SPLITS": {"SPLIT": ["", "", ""]}}}}}}}}}}}

Why not convert Lenex to JSON directly

  • Programs exchanging converted files would first have to agree on one mapping, and writing that mapping down is defining a format.
  • A converter carries only what the XML holds. A Lenex result has its swim time, reaction time, splits and status, but no place for the pad and button readings behind the time, or for how the official time was determined.
  • Lenex keeps its values in attributes, and some converters skip attributes unless told otherwise. The output then keeps the file's shape and drops its values, as fast-xml-parser does above.
  • Attributes become keys like "@swimtime", and the values come through as strings, the lane included, as with xmltodict above.
  • A repeated element becomes an object when there is one and a list when there are several. Maya's one RESULT is an object here; her final would make it a list.

What SwimJSON changes, and why

  • The pad and button readings behind a time, and how the official time was determined, so a records officer can see how a time was decided.
  • A JSON Schema for the structure, with a validator you can run for the rules a schema can't express, such as references that resolve and a last split that matches the final time. Lenex describes its rules in a document and offers a basic upload check.
  • One list of results, each pointing to its swimmer, event and heat and carrying its place, so a results database or a ranking reads the results without walking each club. In Lenex the place is a RANKING under the event's age group, while the result sits under the club and the swimmer.
  • One event with its rounds, so a swimmer's prelim and final sit in the same event. In Lenex each round is its own EVENT, linked to the one before by preveventid.
  • When only a swimmer's birth year is known, SwimJSON writes just the year, "2012". Lenex needs a full date and says to use January 1 of that year, which then looks like a real birthday.
  • Times as people read them, 1:02.88 and +0.71, rather than 00:01:02.88 and +71. Lenex's zero-padded times sort as text and these don't; SwimJSON chose readability, and one rule turns either form into hundredths.

Why JSON

JSON is what web services and apps use to exchange data today, and the format most developers reach for first. It parses straight into the objects, lists, strings and numbers that programming languages have, so a file is ready to use once it's read. XML parses into a tree of elements and attributes that each program maps to its own data.

How it works

SwimJSON documents what each field means and provides checks for the file's structure and relationships. It can also carry the timing readings and source information behind a result, when that information is available.

Plain JSON, with a schema

A SwimJSON file is plain JSON. A schema defines the format, and a validator checks a file against the schema and then against the rules of the sport, such as a last split that should match the final time.

Works with HY3 and Lenex files

The reference converters read an HY3 or Lenex file into SwimJSON and write it back out. You can run them here on a file of your own. Getting Meet Manager to import a converter-written file is work in progress.

Privacy when publishing

The publishing tool removes athlete contact fields and full birth dates. Organizers review the remaining information before sharing the file.

Converter

The reference converter runs on this site. Load the sample meet, or an HY3 or Lenex file of your own, convert it to SwimJSON, check it against the schema, and write it back. Your file is read in your browser, not sent to us.