Open Challenge Protocol

Overview

The Open Challenge Protocol (OCP) is a declarative JSON format for expressing fitness challenges. It defines what constitutes success, not how a host application should implement the experience.

A challenge is a structured goal that evaluates rider performance against defined criteria, with optional lifecycle phases, runtime directives, and iteration/loop logic.

Challenges vs Workouts

OCP is specifically designed for Challenges, not Workouts. Understanding this distinction is critical.

Challenge Structure

A challenge is a JSON object with the following top-level fields:

{
  "id": "string",
  "version": "0.1.0",
  "name": "string",
  "description": "string (optional)",
  "sport": "cycling | running | rowing | any (optional)",

  "mode": "record | pass-fail",

  "config": { },
  "phases": [ ],
  "criteria": { },
  "loops": [ ],
  "directives": [ ],
  "record": { },
  "completion": { },

  "metadata": { }
}

Required Fields

Optional Fields

Challenge Modes

pass-fail (default): Traditional challenge with success/failure criteria. Binary outcome.

record: Best-effort challenge where the goal is to achieve the best possible result. No failure state—the challenge records your performance.

Metrics

Metrics are the canonical data points that challenges evaluate. Host applications map their raw data to these paths.

Metric Path Format

Metrics use dot-notation: category.metric

power.instant     → Current power in watts
power.wkg         → Current power in watts per kilogram
lap.index         → Current lap number (0-indexed or 1-indexed per host)
position.current  → Race position (1 = first place)

Core Metrics

Time

Power

Speed, Cadence, Heart Rate

Distance, Lap, Track

Race/Multiplayer Metrics

These are only available during race contexts:

Phases

Phases define the structure of a challenge as an ordered sequence of segments. Each phase has its own duration, targets, exit conditions, and directives.

Phase Structure

{
  "id": "effort",
  "name": "Max Effort",
  "duration": 30,
  "description": "Give everything for 30 seconds",
  "targets": { },
  "exitConditions": { },
  "directives": [ ]
}

Targets

Targets define the expected or required metrics during a phase:

{
  "targets": {
    "power": { "min": 80, "max": 150 },
    "cadence": { "min": 90, "max": 100 }
  }
}

Ramping Targets

{
  "power": {
    "mode": "ramp",
    "start": 100,
    "increment": 1,
    "per": "second"
  }
}

Conditions

A condition is a single testable expression that evaluates to true or false.

Condition Structure

{
  "metric": "power.wkg",
  "operator": ">=",
  "value": 5.0,
  "duration": 10,
  "window": "sustained"
}

Operators

Duration Windows

Logical Gates

Conditions can be combined using logical gates.

Gate Types

Example: Nested Gates

{
  "all": [
    { "metric": "time.elapsed", "operator": ">=", "value": 60 },
    {
      "any": [
        { "metric": "power.wkg", "operator": ">=", "value": 5.0 },
        { "metric": "position.current", "operator": "==", "value": 1 }
      ]
    }
  ]
}

"After 60 seconds, either hit 5.0 w/kg OR be in first place"

Lifecycle

The lifecycle defines when challenge evaluation begins and ends.

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   PENDING   │ ──▶ │   ARMING    │ ──▶ │   ACTIVE    │ ──▶ │  COMPLETE   │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
                          │                    │
                          │                    ▼
                          │              ┌─────────────┐
                          └────────────▶ │   FAILED    │
                                         └─────────────┘

Lifecycle Structure

{
  "lifecycle": {
    "arming": {
      "all": [
        { "metric": "time.elapsed", "operator": ">=", "value": 120 }
      ]
    },
    "timeout": 600,
    "maxAttempts": 3
  }
}

Success and Failure Criteria

Criteria Structure

{
  "criteria": {
    "success": {
      "all": [
        { "metric": "power.wkg", "operator": ">=", "value": 5.0, "duration": 10 }
      ]
    },
    "failure": {
      "any": [
        { "metric": "power.instant", "operator": "==", "value": 0, "duration": 5 }
      ]
    }
  }
}

Success-Only Challenges

Most challenges only define success criteria. The challenge continues until success or user abandonment.

Challenges with Failure Conditions

{
  "criteria": {
    "success": {
      "all": [
        { "metric": "lap.count", "operator": ">=", "value": 5 }
      ]
    },
    "failure": {
      "any": [
        { "metric": "position.current", "operator": ">", "value": 3 }
      ]
    }
  }
}

"Complete 5 laps while staying in top 3. Drop to 4th or worse = fail."

Loops

Loops enable repeating evaluation blocks with iteration-aware logic. This is essential for challenges that involve multiple intervals, progressive difficulty, or repeated actions.

Loop Structure

{
  "loops": [
    {
      "id": "sprint_intervals",
      "count": 5,
      "trigger": {
        "metric": "lap.index",
        "operator": "increasedBy",
        "value": 1
      },
      "onIteration": {
        "directives": [ ],
        "criteria": { }
      },
      "onComplete": {
        "directives": [ ]
      }
    }
  ]
}

Iteration Context Variables

Progressive Difficulty Example

{
  "loops": [
    {
      "id": "progressive_power",
      "count": 5,
      "trigger": {
        "metric": "time.elapsed",
        "operator": ">=",
        "value": "{{loopIndex * 60}}"
      },
      "onIteration": {
        "directives": [
          {
            "type": "notify",
            "message": "Interval {{loopIndex + 1}}/{{loopCount}}: Hold {{3.0 + loopIndex * 0.5}} w/kg"
          }
        ]
      }
    }
  ]
}

"5 intervals with increasing power: 3.0, 3.5, 4.0, 4.5, 5.0 w/kg"

Directives

Directives are optional runtime behaviors that the host application may execute. They are advisory—the host decides whether to honor them.

Directive Structure

{
  "directives": [
    {
      "id": "gap_warning",
      "type": "notify",
      "when": {
        "metric": "gap.ahead",
        "operator": ">",
        "value": 3.0
      },
      "params": {
        "message": "Gap widening! Push harder.",
        "priority": "high"
      },
      "cooldown": 10
    }
  ]
}

Directive Types

{
  "type": "notify",
  "params": {
    "message": "Push harder!",
    "priority": "normal | high | critical"
  }
}

{
  "type": "sound",
  "params": {
    "sound": "bell | chime | warning | success"
  }
}

{
  "type": "suggest",
  "params": {
    "metric": "power.instant",
    "target": 250
  }
}

{
  "type": "highlight",
  "params": {
    "metric": "power.wkg",
    "style": "pulse | glow | flash"
  }
}

Record (Best Effort Challenges)

For mode: "record" challenges, the record object defines what metrics to capture as the challenge result.

Record Structure

{
  "record": {
    "primary": {
      "metric": "power.max",
      "window": 5,
      "label": "5-Second Max Power",
      "unit": "watts",
      "phase": "effort"
    },
    "secondary": [
      { "metric": "power.peak", "label": "Peak Power", "unit": "watts" },
      { "metric": "cadence.max", "label": "Max Cadence", "unit": "rpm" }
    ]
  }
}

Common Primary Metrics

Completion

The completion object defines how a challenge ends and what to display in the summary.

Completion Structure

{
  "completion": {
    "condition": "phases-complete | exit-or-phases-complete | criteria-met",
    "summary": {
      "headline": "{{record.primary.value}}W",
      "subheadline": "5-Second Max Power"
    }
  }
}

Completion Conditions

Metadata

Metadata provides display hints and categorization for host applications.

{
  "metadata": {
    "difficulty": 4,
    "estimatedDuration": 120,
    "tags": ["sprint", "power", "short"],
    "author": "Ride Cave",
    "icon": "bolt",
    "color": "#FF6B00",
    "shortDescription": "Hold 5.0 w/kg for 10 seconds",
    "requirements": {
      "powerMeter": true,
      "heartRateMonitor": false
    }
  }
}

Complete Example

{
  "id": "power-surge",
  "version": "0.1.0",
  "name": "Power Surge",
  "description": "After a 2-minute warmup, hold 5.0 w/kg for 10 continuous seconds.",
  "sport": "cycling",

  "lifecycle": {
    "arming": {
      "all": [
        { "metric": "time.elapsed", "operator": ">=", "value": 120 }
      ]
    },
    "timeout": 300
  },

  "criteria": {
    "success": {
      "all": [
        {
          "metric": "power.wkg",
          "operator": ">=",
          "value": 5.0,
          "duration": 10,
          "window": "sustained"
        }
      ]
    }
  },

  "directives": [
    {
      "type": "notify",
      "params": {
        "message": "Warmup complete. Go for 5.0 w/kg!"
      },
      "once": true
    },
    {
      "type": "notify",
      "when": {
        "metric": "power.wkg",
        "operator": ">=",
        "value": 4.5
      },
      "params": {
        "message": "Almost there! Push to 5.0!",
        "priority": "high"
      },
      "cooldown": 5
    }
  ],

  "metadata": {
    "difficulty": 4,
    "estimatedDuration": 180,
    "tags": ["sprint", "power", "short"],
    "author": "Ride Cave",
    "shortDescription": "Hold 5.0 w/kg for 10 seconds"
  }
}

Evaluation Model

Evaluation Loop

The challenge evaluator runs at a fixed frequency (recommended: 10Hz).

┌─────────────────────────────────────────────────────────────┐
│                      EVALUATION TICK                        │
├─────────────────────────────────────────────────────────────┤
│  1. Collect current metrics from host                       │
│  2. Check lifecycle phase                                   │
│     - If PENDING: check arming conditions                   │
│     - If ARMING: check arming conditions → transition       │
│     - If ACTIVE: evaluate criteria + loops + directives     │
│  3. Update loop states                                      │
│  4. Check success criteria                                  │
│  5. Check failure criteria (if defined)                     │
│  6. Fire applicable directives                              │
│  7. Return evaluation result                                │
└─────────────────────────────────────────────────────────────┘

Evaluation Result

{
  "phase": "active",
  "success": false,
  "failed": false,
  "progress": {
    "percent": 75,
    "conditions": [
      {
        "metric": "power.wkg",
        "target": 5.0,
        "current": 5.2,
        "durationElapsed": 7.5,
        "durationRequired": 10,
        "met": false
      }
    ]
  },
  "loops": [
    {
      "id": "sprint_intervals",
      "iteration": 2,
      "count": 5,
      "status": "active"
    }
  ],
  "firedDirectives": ["gap_warning"],
  "elapsed": 145.3
}

Appendices

A. Environment & Portability

Challenges may reference environment metrics—values provided by the host application that describe the context in which the challenge runs.

Portability Spectrum

• Fully Portable: Challenges that only reference core metrics (power, cadence, heart rate, time, distance) work on any compliant host
• Environment-Dependent: Challenges that reference environment metrics require the host to provide those values
• Platform-Specific: Some challenges may reference features unique to a specific platform

Fallback Values

{
  "config": {
    "approachDistance": {
      "value": "{{track.length}}",
      "fallback": 250
    }
  }
}

B. Reserved Metric Paths

The following paths are reserved for future use:

• rowing.* - Rowing-specific metrics
• running.* - Running-specific metrics
• strength.* - Strength training metrics
• custom.* - Host-defined custom metrics

C. Host Implementation Notes

Hosts must implement a metric adapter that maps their internal data to OCP metric paths:

interface MetricAdapter {
  resolve(path: string): number | undefined;
  getProfile(): { ftp?: number; weight?: number; maxHr?: number };
}

D. Version History