How to Use `instruction_steps` for Step-by-Step UI Guidance in the Exercises Dataset

The hasaneyldrm/exercises-dataset repository provides instruction_steps as a multilingual object of string arrays, enabling direct integration with stepper components, accordions, and voice-guided interfaces without parsing long-form text.

The hasaneyldrm/exercises-dataset stores structured fitness data where each exercise includes both paragraph-style descriptions and atomic steps. The instruction_steps field contains language-coded arrays designed specifically for progressive UI disclosure, allowing you to build guided workout interfaces by consuming pre-split instruction arrays rather than tokenizing long strings.

Understanding the Schema Structure

The data contract for these fields is defined in data/exercises.schema.json. According to the schema (lines 90-97), both instructions and instruction_steps are required objects that must contain entries for ten supported languages.

The repository distinguishes between two complementary instruction formats:

• instructions: An object mapping language codes to single strings containing full paragraph-style descriptions. Use this for quick display or search functionality.
• instruction_steps: An object mapping language codes to ordered arrays of strings. Each array contains atomic steps ideal for sequential UI presentation.

Supported languages include English, Spanish, Italian, Turkish, Russian, Chinese, Hindi, Polish, Korean, and French. Because the field is language-coded at the root level, you can swap the entire instruction_steps object when changing locales, ensuring consistent formatting across all translations without additional parsing logic.

UI Patterns for Step-by-Step Guidance

The array structure of instruction_steps supports several common interface patterns for fitness applications:

• Stepper Components – Render each array element as a discrete step in a progress bar, displaying the current index and allowing forward/backward navigation.

• Accordion Panels – Present each step as a collapsible section, letting users focus on one movement cue at a time while maintaining context of the overall sequence.

• Voice-Guided Assistants – Consume the array sequentially, speaking each step aloud while the user performs the movement, then advancing to the next index based on voice commands or timers.

• Highlight-on-Tap Interfaces – Synchronize the active step index with visual elements, such as highlighting specific muscle groups on an anatomical diagram as the user scrolls through the instruction array.

Implementation Examples

The following snippets demonstrate how to load data/exercises.json and render instruction_steps for different platforms.

Python Console Renderer

This example loads the dataset and prints numbered steps for a selected language:

import json

# Load the full dataset

with open("data/exercises.json", "r", encoding="utf-8") as f:
    exercises = json.load(f)

# Choose an exercise (e.g., first record) and a language

exercise = exercises[0]                 # change index as needed

lang = "en"                             # could be "es", "it", etc.

steps = exercise["instruction_steps"][lang]

print(f"\n=== {exercise['name']} – {lang.upper()} Steps ===\n")
for i, step in enumerate(steps, start=1):
    print(f"{i}. {step}")

Node.js Express Endpoint

Serve step data via a lightweight API endpoint:

const express = require("express");
const fs = require("fs");
const app = express();

const data = JSON.parse(fs.readFileSync("./data/exercises.json", "utf-8"));

app.get("/exercise/:id/:lang", (req, res) => {
  const { id, lang } = req.params;
  const ex = data.find(e => e.id === id);
  if (!ex) return res.status(404).send("Exercise not found");
  const steps = ex.instruction_steps[lang];
  if (!steps) return res.status(400).send("Unsupported language");
  res.json({ name: ex.name, language: lang, steps });
});

app.listen(3000, () => console.log("Server listening on :3000"));

React Stepper Component

A TypeScript React component that manages active step state:

import React, { useState } from "react";
import exercises from "./data/exercises.json";

interface Props {
  exerciseId: string;
  lang: keyof typeof exercises[0]["instruction_steps"];
}

export const ExerciseStepper: React.FC<Props> = ({ exerciseId, lang }) => {
  const exercise = exercises.find(e => e.id === exerciseId);
  const steps = exercise?.instruction_steps[lang] ?? [];

  const [active, setActive] = useState(0);

  return (
    <div>
      <h2>{exercise?.name} – {lang.toUpperCase()}</h2>
      <ol>
        {steps.map((step, idx) => (
          <li key={idx} style={{ fontWeight: idx === active ? "bold" : "normal" }}>
            {step}
          </li>
        ))}
      </ol>
      <button disabled={active === 0} onClick={() => setActive(active - 1)}>Prev</button>
      <button disabled={active === steps.length - 1} onClick={() => setActive(active + 1)}>Next</button>
    </div>
  );
};

The repository includes index.html, which demonstrates an interactive browser implementation of this pattern, and setup.html, which provides developer guidance for importing the data.

Summary

• instruction_steps stores ordered arrays of strings keyed by language code in data/exercises.json, while instructions stores single paragraphs for the same content.
• The schema in data/exercises.schema.json mandates ten languages (English, Spanish, Italian, Turkish, Russian, Chinese, Hindi, Polish, Korean, French) and requires both fields as objects.
• Array structures enable direct binding to UI components like steppers, accordions, and voice assistants without string parsing or manual splitting.
• Reference implementations are available in index.html (interactive demo) and setup.html (integration guide).

Frequently Asked Questions

What is the difference between instructions and instruction_steps?

The instructions field contains paragraph-style descriptions suitable for quick reading or search, while instruction_steps provides the same content split into ordered arrays. Use instruction_steps when your interface needs to present one movement cue at a time or support step-by-step navigation.

Which languages are supported in instruction_steps?

According to the schema defined in data/exercises.schema.json, the field must contain entries for English, Spanish, Italian, Turkish, Russian, Chinese, Hindi, Polish, Korean, and French. Each language code maps to an array of instruction strings specific to that exercise.

How do I validate my implementation against the official schema?

Validate your consumption logic against data/exercises.schema.json, which explicitly defines instruction_steps as a required object containing language-coded string arrays. You can use JSON Schema validators in Python, JavaScript, or CI pipelines to ensure your code handles the ten mandatory language keys correctly.

Can I use instruction_steps for voice-guided workout applications?

Yes, the sequential array structure is ideal for voice interfaces. Each array element represents a discrete instruction that can be spoken individually, allowing the application to advance to the next step based on voice commands, timers, or user confirmation without parsing complex text strings.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}