MoveSpec YAML reference

MoveSpec definitions are authored in YAML. This page documents the schema structure with well-commented examples covering all available features.

Minimal example

The simplest valid MoveSpec defines a single movement with two phases:

# Every MoveSpec starts with a name and version.
name: squat
version: "1.0"

# The detection block defines what movements to detect.
detection:
  type: repetition          # Count repeated movement cycles.
  movement:
    name: squat
    phases:
      - name: standing      # Starting position.
        criteria:
          - joint: knee
            angle_min: 160
            angle_max: 180
      - name: bottom        # Bottom of the squat.
        criteria:
          - joint: knee
            angle_min: 60
            angle_max: 100
    sequence:               # The phase order that defines one repetition.
      - standing
      - bottom
      - standing

Full-featured example

This example demonstrates all supported schema features:

# Top-level metadata
name: workout-combo
version: "1.0"
description: "Detect a squat-to-lunge combination with feedback cues."

# Detection configuration
detection:
  type: repetition
  movement:
    name: squat-lunge-combo

    # Phases define the discrete positions in the movement.
    phases:
      - name: standing
        description: "Upright standing position"
        criteria:
          - joint: knee
            angle_min: 160
            angle_max: 180
          - joint: hip
            angle_min: 160
            angle_max: 180

      - name: squat-bottom
        description: "Bottom of squat — knees at roughly 90 degrees"
        criteria:
          - joint: knee
            angle_min: 70
            angle_max: 110
          - joint: hip
            angle_min: 70
            angle_max: 110

      - name: lunge-bottom
        description: "Bottom of lunge — front knee bent, back leg extended"
        criteria:
          - joint: knee
            side: front
            angle_min: 70
            angle_max: 100
          - joint: knee
            side: back
            angle_min: 150
            angle_max: 180

    # Sequence defines the phase ordering for one complete repetition.
    sequence:
      - standing
      - squat-bottom
      - standing
      - lunge-bottom
      - standing

    # Feedback cues emitted during detection.
    feedback:
      - trigger: squat-bottom
        cue: "Good depth — hold briefly"
      - trigger: lunge-bottom
        cue: "Keep your back knee extended"

    # Timing constraints (optional).
    timing:
      min_phase_duration_ms: 200   # Ignore phases shorter than 200ms (likely noise).
      max_phase_duration_ms: 5000  # Fail phases longer than 5 seconds.

    # Confidence thresholds (optional).
    thresholds:
      min_landmark_confidence: 0.5  # Ignore frames below this landmark confidence.

Schema reference

Top-level fields

Field	Type	Required	Description
`name`	string	Yes	Human-readable name for the MoveSpec.
`version`	string	Yes	Schema version string (e.g., `"1.0"`).
`description`	string	No	Optional description of the MoveSpec purpose.
`detection`	object	Yes	The detection configuration block.

`detection` object

Field	Type	Required	Description
`type`	string	Yes	Detection mode. Currently `"repetition"` for counting repeated movement cycles.
`movement`	object	Yes	The movement definition.

`movement` object

Field	Type	Required	Description
`name`	string	Yes	Identifier for the movement being detected.
`phases`	array	Yes	List of phase definitions that make up the movement.
`sequence`	array	Yes	Ordered list of phase names defining one repetition cycle.
`feedback`	array	No	Optional feedback cues to emit during detection.
`timing`	object	No	Optional timing constraints for phase transitions.
`thresholds`	object	No	Optional confidence thresholds for frame filtering.

`phase` object

Field	Type	Required	Description
`name`	string	Yes	Unique name for this phase within the movement.
`description`	string	No	Human-readable description of the phase.
`criteria`	array	Yes	List of joint-angle criteria that define the phase.

`criteria` object

Field	Type	Required	Description
`joint`	string	Yes	The joint to evaluate (e.g., `"knee"`, `"hip"`, `"elbow"`, `"shoulder"`).
`angle_min`	number	Yes	Minimum joint angle in degrees (0-180).
`angle_max`	number	Yes	Maximum joint angle in degrees (0-180).
`side`	string	No	Which side to evaluate: `"front"`, `"back"`, `"left"`, `"right"`. Defaults to both sides.

`feedback` object

Field	Type	Required	Description
`trigger`	string	Yes	Phase name that triggers this feedback cue.
`cue`	string	Yes	The feedback message to emit.

`timing` object

Field	Type	Required	Description
`min_phase_duration_ms`	number	No	Minimum phase duration in milliseconds. Phases shorter than this are ignored.
`max_phase_duration_ms`	number	No	Maximum phase duration in milliseconds. Phases exceeding this trigger an interruption.

`thresholds` object

Field	Type	Required	Description
`min_landmark_confidence`	number	No	Minimum landmark confidence (0.0 to 1.0). Frames below this threshold are skipped.

Validation

Always validate your MoveSpec draft before creating a version:

Errors block version creation and must be resolved.
Warnings flag risky but non-blocking YAML patterns.

Use validateDraft() (SDKs) or POST /api/movespecs/{id}/validate (API) to check your YAML before versioning. See MoveSpec validation troubleshooting if validation fails.

​MoveSpec YAML reference

​Minimal example

​Full-featured example

​Schema reference

​Top-level fields

​detection object

​movement object

​phase object

​criteria object

​feedback object

​timing object

​thresholds object

​Validation