The Open Swim Workout format & SwimText

Faithful to the whiteboard

SwimText ⇄ JSON

A real example from the spec repository: friday-sprint, a 3,200-yard short-course sprint workout for three speed groups. The JSON below is abridged to the interesting parts — the full file is downloadable.

# Friday — Sprint
course: scy
categories: sprint
total: 3200

== Warmup: 300
3x100 as swim/kick/pull
== Main Set: 2800
3x300 free descend to 80% @4:40/4:50/5:00 (ideally :40 rest)
100 kick easy r1:00
4x200 free descend to 90% @3:10/3:20/3:30 (ideally :30 rest)
100 kick easy r1:00
5x100 choice descend to 95% @1:30/1:40/1:50 (ideally :20 rest)
100 kick easy r1:00
6x50 choice descend to 100% @1:00/1:10 (ideally :15 rest)
== Cool Down: 100
100 choice easy

{
  "format": "open-swim-workout",
  "version": "0.1",
  "workout": {
    "title": "Friday — Sprint",
    "course": { "length": 25, "unit": "yd" },
    "categories": ["sprint"],
    "groups": [ { "id": "A" }, { "id": "B" }, { "id": "C" } ],
    "sections": [
      { "name": "Warmup", "statedDistance": 300, "items": [ … ] },
      { "name": "Main Set", "statedDistance": 2800, "items": [
        … the 3×300 and 4×200 sets, easy kick 100s …
        {
          "type": "set",
          "reps": 5,
          "distance": 100,
          "stroke": "choice",
          "effort": { "shape": "descend", "percent": 95 },
          "interval": {
            "mode": "sendoff",
            "sendoffs": { "A": "1:30", "B": "1:40", "C": "1:50" },
            "targetRest": ":20"
          },
          "sourceText": "5x100 choice descend to 95% @1:30/1:40/1:50 (ideally :20 rest)"
        },
        … the 6×50 set …
      ] },
      { "name": "Cool Down", "statedDistance": 100, "items": [ … ] }
    ],
    "statedTotal": 3200
  }
}

Repeat blocks

Brace repeats nest, carry per-round variations, and can even run a different number of rounds per group. From the wednesday-im-nested example:

== Main Set: 2000
2x {
  4x75 imo as kick/drill/swim r:20
  100 free sprint @1:30/1:45/2:00 (~:15 rest)
  100 im sprint @1:30/1:45/2:00/2:20 (~:10 rest)
  100 choice easy r1:00
  75 (25 fly/25 back/25 breast) sprint @1:10/1:20/1:30 (~:10 rest)
  …
}

{
  "type": "repeat",
  "rounds": 2,
  "items": [
    {
      "type": "set",
      "reps": 4, "distance": 75, "stroke": "imo",
      "segments": [
        { "distance": 25, "activity": "kick" },
        { "distance": 25, "activity": "drill" },
        { "distance": 25, "activity": "swim" }
      ],
      "interval": { "mode": "rest", "rest": ":20" }
    },
    {
      "type": "set",
      "reps": 1, "distance": 100, "stroke": "free",
      "effort": { "level": "sprint" },
      "interval": {
        "mode": "sendoff",
        "sendoffs": { "A": "1:30", "B": "1:45", "C": "2:00" },
        "targetRest": ":15"
      }
    },
    …
  ]
}

Speed groups: one workout, many speeds

A speed group is a lane or pace cohort, declared once per workout and ordered fastest → slowest. Sets carry a send-off map from group id to time — exactly what coaches write as @1:30/1:45/2:00. Groups can also override reps or distance per set, and items can be filtered to specific groups.

Sparse maps are legal — and resolved deterministically. A group with no entry resolves to the nearest faster (earlier-listed) specified group, then to the nearest slower one. That encodes the everyday reality of a coach listing three times in a four-lane workout. In wednesday-im-nested, the line 100 free sprint @1:30/1:45/2:00 appears in a workout with four groups:

Strokes, activities, effort

Stroke and activity are orthogonal axes: “fly drill” is simply stroke: fly + activity: drill — a combination most formats cannot express.

All times are strings — "1:30", ":35", or bare seconds "35" — emitted canonically as m:ss, with :ss for sub-minute values. Validators flag non-positive reps, segment sums that don’t match the rep distance, undefined group ids, totals matching no group, distances not divisible by the course length, and send-offs implausibly shorter than the estimated swim time.

Schema & examples

Everything is versioned with the spec (semantic versioning: readers MUST reject unknown major versions, SHOULD accept unknown minors, and ignore unknown fields — ideally preserving them on rewrite).

SwimWorkoutKit

$ swimtext check friday-sprint.swimtext
group A: 3200 yd, ~40:10 (partial)
group B: 3200 yd, ~43:10 (partial)
group C: 3200 yd, ~45:10 (partial)

SwimText syntax highlighting, built in

The optional SwimWorkoutKitUI module colors SwimText with the same visual vocabulary as the app and its deck sheets — strokes, activities, effort, send-offs, sections, and notes — so a typed or pasted workout reads at a glance. It's color-blind-safe and pairs color with weight, staying legible in black & white.

import SwiftUI
import SwimWorkoutKitUI

struct WorkoutEntry: View {
  @State private var text = "8x50 free fast @:45 r:10"
  var body: some View {
    SwimTextEditor(text: $text)   // live highlighting
  }
}

# Friday — Sprint
course: scy
== Warmup: 300
3x100 as swim/kick/pull
== Main Set: 2800
3x300 free descend to 80% @4:40/4:50/5:00
2x {
  6x25 fly sprint @:35
  100 back smooth r:20 | long axis
}
> remember your fins