# How to Parse and Use the instruction_steps Array for Exercise Guidance in hasaneyldrm/exercises-dataset

> Learn to parse the instruction_steps array in hasaneyldrm/exercises-dataset. Get deterministic, step-by-step exercise guidance by leveraging structured data for clear instructions.

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

---

**The `instruction_steps` property stores language-specific exercise instructions as ordered arrays of strings in [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json), enabling deterministic rendering of step-by-step guides without parsing unstructured text.**

The **hasaneyldrm/exercises-dataset** repository provides a structured JSON dataset where each exercise entry contains an `instruction_steps` object designed for programmatic consumption. Unlike the free-text `instructions` field, this array structure delivers deterministic, language-aware breakdowns that frontend applications can render directly into numbered lists, carousel slides, or voice-over prompts.

## Understanding the instruction_steps Data Structure

### JSON Schema and Language Keys

In [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json), the `instruction_steps` field appears as a map object where keys follow **ISO-639-1 language codes** (`en`, `it`, `zh`, etc.) and values are ordered arrays of instruction strings.

```json
{
  "id": "0001",
  "name": "Push-up",
  "instruction_steps": {
    "en": [
      "Lie flat on your back …",
      "Place your hands behind your head …"
    ],
    "it": [
      "Stenditi sulla schiena …",
      "Metti le mani dietro la testa …"
    ],
    "zh": [
      "平躺在地上 …",
      "双手放在头后 …"
    ]
  }
}

```

The array order represents the exact sequence users should follow, making this structure ideal for UI components that require sequential presentation.

## Loading and Parsing the Exercise Data

### Accessing data/exercises.json

To parse and use the `instruction_steps` array, first load the master data file located at the repository root. Each exercise entry contains a unique `id` field for lookup and the multilingual `instruction_steps` object.

```python
import json

def load_exercise(ex_id, lang='en'):
    with open('data/exercises.json', encoding='utf-8') as f:
        data = json.load(f)
    ex = next((e for e in data if e['id'] == ex_id), None)
    if not ex:
        raise ValueError('Exercise not found')
    return ex

```

## Implementing Language Resolution Strategies

### Handling Missing Translations

Production applications must implement fallback logic when the requested locale is unavailable. The recommended resolution order is: user preference → English (`en`) → empty array.

```tsx
// Example React component with fallback logic
import React from 'react';
import exercises from '../data/exercises.json';

type Props = { id: string; locale: string };

export const ExerciseSteps: React.FC<Props> = ({ id, locale }) => {
  const exercise = exercises.find((e) => e.id === id);
  if (!exercise) return <p>Exercise not found</p>;

  // Choose the language; fallback to English
  const steps = (exercise.instruction_steps[locale] ??
                exercise.instruction_steps['en'] ??
                []);

  if (steps.length === 0) return <p>No step-by-step guide available.</p>;

  return (
    <ol>
      {steps.map((step, idx) => (
        <li key={idx}>{step}</li>
      ))}
    </ol>
  );
};

```

## Rendering Step-by-Step Guides in Practice

### React Component Implementation

For React applications, map the `instruction_steps` array directly to ordered list elements. This approach maintains the sequence integrity defined in the source data.

```tsx
// React component implementation
import React from 'react';
import exercises from '../data/exercises.json';

type Props = { id: string; locale: string };

export const ExerciseSteps: React.FC<Props> = ({ id, locale }) => {
  const exercise = exercises.find((e) => e.id === id);
  if (!exercise) return <p>Exercise not found</p>;

  const steps = (exercise.instruction_steps[locale] ??
                exercise.instruction_steps['en'] ??
                []);

  if (steps.length === 0) return <p>No step-by-step guide available.</p>;

  return (
    <ol>
      {steps.map((step, idx) => (
        <li key={idx}>{step}</li>
      ))}
    </ol>
  );
};

```

### Python CLI Parser

Command-line tools can iterate through the array with enumeration for numbered output.

```python
import json

def load_exercise(ex_id, lang='en'):
    with open('data/exercises.json', encoding='utf-8') as f:
        data = json.load(f)
    ex = next((e for e in data if e['id'] == ex_id), None)
    if not ex:
        raise ValueError('Exercise not found')
    steps = ex['instruction_steps'].get(lang) or ex['instruction_steps'].get('en')
    return steps

# Usage example

for i, step in enumerate(load_exercise('0001', 'es'), 1):
    print(f'{i}. {step}')

```

### Vanilla JavaScript Integration

For static HTML pages, fetch the JSON and render steps dynamically.

```html
<ul id="steps"></ul>
<script>
fetch('data/exercises.json')
  .then(r => r.json())
  .then(data => {
    const ex = data.find(e => e.id === '0002');
    const steps = (ex.instruction_steps['zh'] || ex.instruction_steps['en']);
    const ul = document.getElementById('steps');
    steps.forEach(s => {
      const li = document.createElement('li');
      li.textContent = s;
      ul.appendChild(li);
    });
  });
</script>

```

## Handling Edge Cases and Data Integrity

### Empty Arrays and Missing Keys

Some exercises may lack translations for specific languages or contain empty `instruction_steps` arrays. Always validate array length before rendering and provide appropriate user messaging when no step-by-step guidance exists.

### Future-Proofing Against Markup

While current strings are plain text, future releases may include lightweight markup (bold markers or emphasis). Implement sanitization pipelines when rendering to prevent injection vulnerabilities while preserving intended formatting.

## Summary

- **Source Location**: The `instruction_steps` array resides in [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json) within the **hasaneyldrm/exercises-dataset** repository.
- **Data Structure**: Map of ISO-639-1 language codes to ordered string arrays representing sequential exercise steps.
- **Language Fallback**: Always implement user-locale → English → empty array resolution chains.
- **Rendering Strategy**: Iterate arrays directly into ordered lists without splitting or parsing free-text.
- **Edge Cases**: Handle missing translations, empty arrays, and potential future markup safely.

## Frequently Asked Questions

### What is the difference between the `instructions` and `instruction_steps` fields?

The `instructions` field contains a single free-text string suitable for human reading but difficult to parse programmatically. The `instruction_steps` field provides a deterministic, language-specific array structure that eliminates the need for text splitting or natural language processing.

### Which languages are supported in the instruction_steps array?

The dataset uses **ISO-639-1 language codes** as keys (such as `en` for English, `it` for Italian, and `zh` for Chinese). However, not every exercise contains translations for every language, making the English fallback essential.

### How should I handle exercises without steps in my target language?

When the requested language key is missing or the array is empty, fall back to English (`en`). If English is also unavailable, display a "No step-by-step guide available" message rather than attempting to parse the monolithic `instructions` string.

### Can instruction_steps contain HTML or markdown formatting?

Currently, strings are plain text, but future versions may include lightweight markup. You should render content through a sanitization library to safely handle any embedded formatting while preventing XSS vulnerabilities.