Skip to content

Overview

The Structured Workout Format (SWF) is a JSON-based specification for representing structured workouts in endurance sports. It was designed to be simple, flexible, and powerful enough to represent both basic and complex training sessions.

Design Philosophy

  • Universal Interchange: SWF serves as an intermediate format for converting between different training platforms, enabling ecosystem interoperability.
  • Simplicity First: Although every JSON format is inherently verbose, SWF aims to be readable, editable and easy to understand for developers.
  • Precise Specification: Every aspect of a workout can be precisely defined, from exact power targets to flexible ranges and progressive ramps.
  • Sport Agnostic: While initially focused on cycling and running, SWF aims to support any (endurance) sport through its flexible quantity and unit system.
  • Parameterized: SWF supports variables for creating reusable workout templates.

Core Concepts

Quantities & Units

SWF uses a standardized unit system for all measurements:

  • Duration: Time in seconds
  • Distance: Distance in meters
  • Speed: Velocity in meters per second (m/s)
  • Power: Power output in watts (W)
  • Heart Rate: Beats per minute (bpm) [planned]
  • Perceived Exertion: RPE scale 1-10 [planned]

Value Specifications

All numeric values in SWF use a consistent specification pattern:

Constant Values

A single, exact target: 

{
  "type": "constant",
  "quantity": "power",
  "value": {
    "reference": "absolute",
    "value": 250
  }
}

Range Values

A target range with optional bounds: 

{
  "type": "range",
  "quantity": "power",
  "min": {
    "reference": "absolute",
    "value": 200
  },
  "max": {
    "reference": "absolute",
    "value": 250
  }
}

Ramp Values

Linear progression between two points: 

{
  "type": "ramp", 
  "quantity": "power",
  "start": {
    "reference": "absolute",
    "value": 200
  },
  "end": {
    "reference": "absolute",
    "value": 300
  }
}

Variables & Templating

SWF supports parameters for creating reusable workout templates:

{
  "type": "constant",
  "quantity": "power",
  "value": {
    "reference": "parameter",
    "value": 0.85,
    "parameter": "FTP"
  }
}

This allows workouts to scale automatically based on an athlete's current fitness metrics.

Workout Structure

At the highest level, a SWF workout is a JSON object with the following properties:

{
  "title": "Workout Name",
  "description": "Optional description", 
  "version": "1.0.0",
  "content": [
    // Array of sections, intervals, repeats, instructions
  ]
}

Workout Content

Every SWF workout is composed of these 4 fundamental content elements that can be nested:

  • Intervals: A single interval specifying how long (volume) and hard (intensity) to train.
  • Sections: Logical grouping of workout sections (warmup, main set, cooldown, etc.)
  • Repeats: Recurring patterns
  • Instructions: Text guidance for athletes

Intervals

The basic unit combining volume (how long/far) with intensity (how hard):

{
  "type": "interval",
  "volume": {
    "type": "constant",
    "quantity": "duration",
    "value": {
      "reference": "absolute",
      "value": 300
    }
  },
  "intensity": {
    "type": "constant",
    "quantity": "power",
    "value": {
      "reference": "absolute",
      "value": 250
    }
  }
}

Sections

Logical grouping of workout parts:

{
  "type": "section",
  "name": "main set",
  "content": [
    // intervals, repeats, instructions, or even other sections...
  ]
}

Special section names have semantic meaning: - "warm up" - Preparation phase - "main set" - Primary training stimulus
- "cool down" - Recovery phase

Repeats

For recurring patterns:

{
  "type": "repeat", 
  "count": {
    "type": "constant",
    "quantity": "number",
    "value": {
      "reference": "absolute",
      "value": 5
    }
  },
  "content": [
    // repeating intervals, sections, instructions, or even other repeats...
  ]
}

Instructions

Text guidance for athletes:

{
  "type": "instruction",
  "text": "Focus on smooth pedaling technique"
}

Advanced Features

Nested Structures

Sections can contain repeats, repeats can contain sections, allowing complex workout structures:

{
  "type": "section",
  "name": "main set",
  "content": [
    {
      "type": "repeat",
      "count": {
        "type": "constant",
        "quantity": "number",
        "value": {
          "reference": "absolute",
          "value": 3
        }
      },
      "content": [
        {
          "type": "section", 
          "name": "set",
          "content": [
            // intervals within repeated sections
          ]
        }
      ]
    }
  ]
}

Parameter References

Fine-tune parameter usage:

{
  "type": "range",
  "quantity": "power",
  "min": {
    "reference": "parameter",
    "value": 0.7,
    "parameter": "FTP"
  },
  "max": {
    "reference": "parameter",
    "value": 0.85,
    "parameter": "FTP"
  }
}

Open-Ended Ranges

Create "at least" or "at most" targets:

{
  "type": "range",
  "quantity": "duration",
  "min": {
    "reference": "absolute",
    "value": 1200
  }  // At least 20 minutes
}

Integration & Ecosystem

Reference Implementation

The official Python library provides: - Complete SWF parsing and generation
- Validation and error handling - Conversion utilities - Type hints and comprehensive documentation

Format Conversions

SWF can convert to/from popular formats: - Intervals.icu workout builder format - Garmin Connect structured workouts - Zwift .zwo files - TrainerRoad .erg files
- MRC format files

See the compatibility section for detailed compatibility information.

Next Steps