Format Specification¶

This page provides the complete technical specification for the Structured Workout Format (SWF).

Workout Root Object¶

Every SWF file represents a single workout with this top-level structure:

{
  "title": "string (optional)",
  "description": "string (optional)", 
  "content": [
    // Array of workout elements
  ]
}

Fields¶

Field	Type	Required	Description
`title`	string	No	Human-readable workout name
`description`	string	No	Extended workout description
`content`	array	Yes	Array of workout elements (intervals, sections, repeats, instructions)

Value Specifications¶

Value specifications define numeric targets and are used throughout SWF for volumes, intensities, and counts. The new schema uses a unified approach with three intensity types and three reference types.

Common Fields¶

All value specifications share these base fields:

Field	Type	Required	Description
`type`	string	Yes	One of: `"constant"`, `"range"`, `"ramp"`
`quantity`	string	Yes	The type of measurement (see Quantities)

Constant Values¶

Represents a single target value:

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

Additional Fields¶

Field	Type	Required	Description
`value`	object	Yes	Value object with reference and value

Range Values¶

Represents a target range between min and max values. Both min and max are optional - you can specify just one to create an open-ended range:

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

Additional Fields¶

Field	Type	Required	Description
`min`	object	No	Minimum value object (omit for open-ended)
`max`	object	No	Maximum value object (omit for open-ended)

At least one bound required

Either min or max must be specified.

Open-ended Range Example¶

{
  "type": "range",
  "quantity": "speed",
  "min": {
    "reference": "absolute",
    "value": 2.5
  }
}

Ramp Values¶

Represents linear progression between two values:

{
  "type": "ramp",
  "quantity": "speed",
  "start": {
    "reference": "absolute",
    "value": 2.5
  },
  "end": {
    "reference": "absolute",
    "value": 3.5
  }
}

Additional Fields¶

Field	Type	Required	Description
`start`	object	Yes	Starting value object
`end`	object	Yes	Ending value object

Reference Types¶

Each value uses a reference field to specify how the intensity should be interpreted:

1. Absolute Reference¶

Direct, literal values:

{
  "reference": "absolute",
  "value": 250
}

2. Parameter Reference¶

Fractions of named variables (e.g., percentages of FTP):

{
  "reference": "parameter",
  "value": 0.75,
  "parameter": "FTP"
}

3. Time-to-Exhaustion (TTE) Reference¶

Intensities based on how long you can sustain them:

{
  "reference": "tte",
  "value": 300
}

This represents "the power (or speed) you can hold for 300 seconds".

Complete Reference Examples¶

Parameter-based intensity (75% of FTP):¶

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

TTE-based intensity:¶

{
  "type": "constant",
  "quantity": "power",
  "value": {
    "reference": "tte",
    "value": 600
  }
}

Range with mixed references:¶

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

Ramp from absolute to parameter:¶

{
  "type": "ramp",
  "quantity": "power",
  "start": {
    "reference": "absolute",
    "value": 150
  },
  "end": {
    "reference": "parameter",
    "value": 0.9,
    "parameter": "FTP"
  }
}

Quantities¶

SWF defines standard quantities and units:

Volume Quantities¶

Quantity	Unit	Description
`duration`	seconds	Time duration
`distance`	meters	Distance

Intensity Quantities¶

Quantity	Unit	Description
`speed`	m/s	Velocity
`power`	watts	Power output

Count Quantities¶

Quantity	Unit	Description
`number`	count	Dimensionless count (for repeats)

Future Quantities

Additional quantities like heart_rate (bpm) and perceived_exertion (RPE) are planned for future versions.

Workout Elements¶

Intervals¶

The fundamental building block combining volume and intensity:

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

Fields¶

Field	Type	Required	Description
`type`	string	Yes	Must be `"interval"`
`volume`	object	Yes	Value specification for volume
`intensity`	object	Yes	Value specification for intensity

Example with Ramp Intensity¶

{
  "type": "interval",
  "volume": {
    "type": "constant",
    "quantity": "duration",
    "value": {
      "reference": "absolute",
      "value": 300
    }
  },
  "intensity": {
    "type": "ramp",
    "quantity": "power",
    "start": {
      "reference": "absolute",
      "value": 200
    },
    "end": {
      "reference": "absolute",
      "value": 300
    }
  }
}

Sections¶

Logical groupings of workout elements:

{
  "type": "section",
  "name": "warm up",
  "content": [
    // Array of workout elements
  ]
}

Fields¶

Field	Type	Required	Description
`type`	string	Yes	Must be `"section"`
`name`	string	Yes	Section name
`content`	array	Yes	Array of workout elements

Special Section Names¶

These names have semantic meaning and may receive special treatment by applications:

"warm up" - Preparation phase
"main set" - Primary training stimulus
"cool down" - Recovery phase

Repeats¶

For recurring patterns in workouts:

{
  "type": "repeat",
  "count": {
    "type": "constant",
    "quantity": "number",
    "value": {
      "reference": "absolute",
      "value": 4
    }
  },
  "content": [
    // Array of elements to repeat
  ]
}

Fields¶

Field	Type	Required	Description
`type`	string	Yes	Must be `"repeat"`
`count`	object	Yes	Value specification with `quantity: "number"`
`content`	array	Yes	Array of workout elements to repeat

Example with Range Count¶

{
  "type": "repeat",
  "count": {
    "type": "range",
    "quantity": "number",
    "min": {
      "reference": "absolute",
      "value": 3
    },
    "max": {
      "reference": "absolute",
      "value": 5
    }
  },
  "content": [
    {
      "type": "interval",
      "volume": {
        "type": "constant",
        "quantity": "duration",
        "value": {
          "reference": "absolute",
          "value": 240
        }
      },
      "intensity": {
        "type": "constant",
        "quantity": "power",
        "value": {
          "reference": "absolute",
          "value": 300
        }
      }
    }
  ]
}

Example with Parameter Count¶

{
  "type": "repeat",
  "count": {
    "type": "constant",
    "quantity": "number",
    "value": {
      "reference": "parameter",
      "value": 1.0,
      "parameter": "INTERVAL_COUNT"
    }
  },
  "content": [
    // ... intervals ...
  ]
}

Instructions¶

Text guidance for athletes:

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

Fields¶

Field	Type	Required	Description
`type`	string	Yes	Must be `"instruction"`
`text`	string	Yes	Instruction text

Nesting Rules¶

SWF elements can be nested with these rules:

Allowed Nesting¶

Sections can contain: intervals, repeats, other sections, instructions
Repeats can contain: intervals, sections, other repeats, instructions
Root content can contain: intervals, sections, repeats, instructions

Validation Rules¶

No empty content: Sections and repeats must contain at least one element
Valid element types: Only the four element types are allowed
Consistent quantities: Parameters must be used consistently for the same quantity type
Required fields: All required fields must be present
Value constraints: Numeric values must be positive where applicable

JSON Schema¶

Schema Availability

A complete JSON Schema for validation is available in the GitHub repository.

Validation & Errors¶

Common Validation Errors¶

Error	Description	Solution
Missing required field	Required field not present	Add the missing field
Invalid element type	Unknown `type` value	Use valid element type
Empty content array	Section/repeat with no content	Add at least one element
Invalid quantity	Unknown quantity name	Use supported quantity
Negative values	Negative numeric values	Use positive values
Parameter inconsistency	Same parameter used for different quantities	Use consistent parameter quantities

Best Practices¶

Always validate your SWF files against the schema
Use meaningful names for sections and parameters
Include descriptions for complex workouts
Test conversions when integrating with other platforms
Handle parameters gracefully when they're not provided

Next Steps¶

Examples - See real-world SWF usage
Python Library - Parse and generate SWF programmatically
Compatibility - Convert to/from other formats