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

The instruction_steps property stores language-specific exercise instructions as ordered arrays of strings in 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, 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.

{
  "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.

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.

// 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.

// 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.

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.

<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 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.

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