Open Challenge Protocol

Aperçu

L'Open Challenge Protocol (OCP) est un format JSON déclaratif pour décrire des défis sportifs. Il définit ce qui constitue la réussite, pas comment une application hôte doit mettre en œuvre l'expérience.

Un défi est un objectif structuré qui évalue la performance du cycliste selon des critères définis, avec en option des phases de cycle de vie, des directives d'exécution et une logique d'itération/boucle.

Défis et séances

L'OCP est conçu spécifiquement pour les Défis, pas pour les séances. Il est essentiel de bien comprendre cette distinction.

Structure du défi

Un défi est un objet JSON avec les champs de premier niveau suivants :

{
  "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": { }
}

Champs obligatoires

Champs facultatifs

Modes de défi

pass-fail (par défaut) : défi classique avec critères de réussite/échec. Résultat binaire.

record : défi au meilleur effort, où le but est d'obtenir le meilleur résultat possible. Aucun état d'échec : le défi enregistre ta performance.

Mesures

Les métriques sont les points de données canoniques que les défis évaluent. Les applications hôtes relient leurs données brutes à ces chemins.

Format des chemins de métriques

Les métriques utilisent la notation pointée : 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)

Métriques de base

Temps

Puissance

Vitesse, cadence, fréquence cardiaque

Distance, Lap, Track

Métriques compétition/multijoueur

Ces métriques ne sont disponibles qu'en contexte de compétition :

Phases

Les phases définissent la structure d'un défi sous forme de séquence ordonnée de segments. Chaque phase a sa propre durée, ses cibles, ses conditions de sortie et ses directives.

Structure d'une phase

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

Cibles

Les cibles définissent les métriques attendues ou requises pendant une phase :

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

Cibles progressives

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

Conditions

Une condition est une expression testable unique qui renvoie vrai ou faux.

Structure d'une condition

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

Opérateurs

Fenêtres de durée

Portes logiques

Les conditions peuvent être combinées avec des portes logiques.

Types de portes

Exemple : portes imbriquées

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

« Après 60 secondes, atteindre 5,0 w/kg OU être en tête »

Cycle de vie

Le cycle de vie définit quand l'évaluation du défi commence et se termine.

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

Structure du cycle de vie

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

Critères de réussite et d'échec

Structure des critères

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

Défis à réussite seule

La plupart des défis ne définissent que des critères de réussite. Le défi continue jusqu'à la réussite ou l'abandon de l'utilisateur.

Défis avec conditions d'échec

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

« Boucler 5 tours en restant dans le top 3. Tomber 4e ou pire = échec. »

Boucles

Les boucles permettent de répéter des blocs d'évaluation avec une logique tenant compte de l'itération. C'est indispensable pour les défis qui comportent plusieurs intervalles, une difficulté progressive ou des actions répétées.

Structure de boucle

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

Variables de contexte d'itération

Exemple de difficulté progressive

{
  "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 intervalles à puissance croissante : 3,0, 3,5, 4,0, 4,5, 5,0 w/kg »

Directives

Les directives sont des comportements d'exécution optionnels que l'application hôte peut appliquer. Elles sont indicatif : l'hôte décide de les suivre ou non.

Structure d'une directive

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

Types de directives

{
  "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 (défis au meilleur effort)

Pour les défis mode: "record", l'objet record définit les métriques à enregistrer comme résultat du défi.

Structure du record

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

Métriques principales courantes

Achèvement

L'objet completion définit comment un défi se termine et ce qu'il faut afficher dans le résumé.

Structure d'achèvement

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

Conditions d'achèvement

Métadonnées

Les métadonnées fournissent des indications d'affichage et une catégorisation pour les applications hôtes.

{
  "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
    }
  }
}

Exemple complet

{
  "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"
  }
}

Modèle d'évaluation

Boucle d'évaluation

L'évaluateur de défis tourne à une fréquence fixe (recommandée : 10 Hz).

┌─────────────────────────────────────────────────────────────┐
│                      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                                │
└─────────────────────────────────────────────────────────────┘

Résultat de l'évaluation

{
  "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
}

Annexes

A. Environnement et portabilité

Les défis peuvent faire référence à des métriques d'environnement, des valeurs fournies par l'application hôte qui décrivent le contexte dans lequel le défi se déroule.

Spectre de portabilité

• Entièrement portable : Les défis qui ne font référence qu'aux métriques de base (puissance, cadence, fréquence cardiaque, temps, distance) fonctionnent sur n'importe quel hôte compatible
• Dépendant de l'environnement : Les défis qui font référence à des métriques d'environnement exigent que l'hôte fournisse ces valeurs
• Spécifique à la plateforme : Certains défis peuvent faire référence à des fonctionnalités propres à une plateforme

Valeurs de repli

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

B. Chemins de métriques réservés

Les chemins suivants sont réservés pour un usage futur :

• rowing.* - Métriques propres à l'aviron
• running.* - Métriques propres à la course à pied
• strength.* - Métriques de renforcement
• custom.* - Métriques personnalisées définies par l'hôte

C. Notes d'implémentation pour l'hôte

Les hôtes doivent implémenter un adaptateur de métriques qui relie leurs données internes aux chemins de métriques OCP :

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

D. Historique des versions