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

> Learn how to work with step-by-step exercise instructions from the exercises dataset. Access ordered steps in instruction_steps.<lang> for 10 languages using the provided JSON schema for validation.

- Repository: [Hasan Emir Yıldırım/exercises-dataset](https://github.com/hasaneyldrm/exercises-dataset)
- Tags: how-to-guide
- Published: 2026-08-01

---

**Access the `instruction_steps.<lang>` array in [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json) to retrieve ordered steps for any of the 10 supported languages, using the JSON Schema in [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json) (containing **1,324** exercise records).
2. Validate against [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/index.html) and [`setup.html`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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:

```python
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:

```javascript
// 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:

```typescript
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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json) into your application's data layer or import it into your backend database using the import scripts referenced in [`setup.html`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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.