How to Work with Step-by-Step Exercise Instructions in the Exercises Dataset

Access the instruction_steps.<lang> array in data/exercises.json to retrieve ordered steps for any of the 10 supported languages, using the JSON Schema in data/exercises.schema.json for validation.

The hasaneyldrm/exercises-dataset repository stores fitness instructions in a dual-format structure that supports both full-text display and granular step-by-step breakdowns. Whether you are building a workout app, a voice-guided trainer, or a data pipeline, understanding how to extract and manipulate these sequential instructions is essential for presenting clear guidance to users.

Understanding the Data Structure

Every exercise record in the dataset contains complementary fields for instructions, allowing developers to choose between displaying a complete description or iterating through discrete actions.

Full Text vs. Step Arrays

Each exercise provides two parallel representations for every supported language:

• instructions.<lang> – A single string containing the complete, free-text description of the exercise (e.g., instructions.en).
• instruction_steps.<lang> – An array of strings representing the same content split into ordered, discrete steps (e.g., instruction_steps.en).

According to the JSON Schema defined in data/exercises.schema.json, both fields are required properties for valid records. This dual representation enables you to render a quick summary view using the full text, while simultaneously supporting a detailed wizard or progress tracker using the step array.

Multilingual Support

The dataset supports 10 languages: English (en), Spanish (es), Italian (it), Turkish (tr), Russian (ru), Chinese (zh), Hindi (hi), Polish (pl), Korean (ko), and French (fr). Each language code serves as a key under both the instructions and instruction_steps objects, ensuring consistent access patterns regardless of locale.

Loading and Validating the Data

Before processing step-by-step instructions, load the master dataset and optionally validate it against the schema:

1. Load data/exercises.json (containing 1,324 exercise records).
2. Validate against data/exercises.schema.json if strict conformance is required.
3. Select an exercise by id, name, category, or equipment.
4. Access instruction_steps.<lang> to retrieve the ordered array.

This workflow applies equally to server-side scripts and the client-side browser tools (index.html and setup.html) included in the repository.

Code Examples

Python – Iterate Through Exercise Steps

The following script loads the dataset, selects the first exercise, and prints both the full description and the numbered steps:

import json
from pathlib import Path

# Load the dataset

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

# Select the first exercise

ex = exercises[0]
lang = "en"

# Display full text

print("Full description:")
print(ex["instructions"][lang])

# Iterate through step-by-step instructions

print("\nStep-by-step:")
for i, step in enumerate(ex["instruction_steps"][lang], start=1):
    print(f"{i}. {step}")

JavaScript (Node) – Filter and Display

Filter exercises by category and output the step array for filtered results:

// Load the JSON file
const exercises = require("./data/exercises.json");

// Filter for chest exercises
const chestExercises = exercises.filter(e => e.category === "chest");

// Process the first match
const ex = chestExercises[0];
const lang = "en";

console.log(`\n${ex.name} – Steps (${lang}):`);
ex.instruction_steps[lang].forEach((step, idx) => {
  console.log(`${idx + 1}. ${step}`);
});

TypeScript – Type-Safe Access

Define interfaces to ensure compile-time safety when accessing multilingual instruction arrays:

interface Exercise {
  id: string;
  name: string;
  category: string;
  equipment: string;
  instructions: Record<string, string>;
  instruction_steps: Record<string, string[]>;
}

import exercises from "./data/exercises.json";
const data: Exercise[] = exercises as Exercise[];

// Retrieve French steps for a specific exercise
const deadlift = data.find(e => e.name.includes("Deadlift"))!;
const stepsFr = deadlift.instruction_steps.fr;

console.log("Étapes de deadlift :");
stepsFr.forEach((s, i) => console.log(`${i + 1}. ${s}`));

Browser-Based Exploration

For immediate visual feedback without writing code, open index.html in any modern browser. The interface provides:

• Search functionality by name, category, and equipment.
• A detail pane that opens when selecting an exercise card.
• A language selector that switches between the 10 supported locales.
• Automatic rendering of the instruction_steps.<lang> array as a numbered list.

The browser tool runs entirely client-side, parsing data/exercises.json directly via JavaScript, making it ideal for quick data exploration or demonstrating the step-by-step structure to stakeholders.

Summary

• Dual format: Each exercise stores both instructions.<lang> (full text) and instruction_steps.<lang> (array) for flexible display options.
• Schema validation: The structure is enforced by data/exercises.schema.json, ensuring both fields exist for every supported language.
• Ten languages: Access steps via language keys (en, es, it, tr, ru, zh, hi, pl, ko, fr).
• 1,324 records: The master file data/exercises.json contains over one thousand exercises with complete step data.
• Multiple access methods: Use Python, JavaScript/Node, TypeScript, or the built-in index.html browser interface to consume the data.

Frequently Asked Questions

How do I validate that an exercise has step-by-step instructions before accessing them?

The JSON Schema in data/exercises.schema.json defines both instructions and instruction_steps as required objects containing language-specific properties. If you validate your data against this schema using libraries like jsonschema (Python) or Ajv (JavaScript), you can guarantee that instruction_steps.<lang> exists for all 10 supported languages before runtime access.

Can I display steps in multiple languages simultaneously?

Yes. Since instruction_steps contains keys for all supported languages (e.g., instruction_steps.en and instruction_steps.es), you can render parallel columns or toggle between languages without reloading the dataset. Simply access the specific language key on the same exercise object and iterate through the array as shown in the code examples.

What is the difference between instructions and instruction_steps?

The instructions field contains a single string with the complete exercise description, suitable for summary views or logs. The instruction_steps field contains an array of strings where each element represents a discrete action, designed for UI components like numbered lists, progress indicators, or voice prompts that require sequential highlighting of individual movements.

How do I integrate this data into a mobile fitness app?

Load data/exercises.json into your application's data layer or import it into your backend database using the import scripts referenced in setup.html. Query exercises by metadata fields (category, equipment, muscle groups), then pass the instruction_steps.<lang> array to your frontend components. Because the steps are plain text strings, they render natively in React Native, Flutter, Swift, or Android views without requiring HTML parsing.

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