# Exercises JSON Schema Structure: Complete Guide to the hasaneyldrm/exercises-dataset Format

> Explore the hasaneyldrm/exercises-dataset JSON schema structure. Understand how each multilingual exercise object is defined, including id, name, body_part, and detailed instructions for complete data validation.

- Repository: [Hasan Emir Yıldırım/exercises-dataset](https://github.com/hasaneyldrm/exercises-dataset)
- Tags: api-reference
- Published: 2026-07-31

---

**The exercises JSON schema defines a root array where each element is a multilingual exercise object with fields like `id`, `name`, `body_part`, and nested language maps for instructions, all validated via [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json).**

The `hasaneyldrm/exercises-dataset` repository provides a structured dataset for fitness exercises governed by a strict JSON Schema. The schema ensures consistent data modeling across multilingual instruction sets, media references, and anatomical classifications, making it ideal for integration into fitness applications and analysis pipelines.

## Root Schema Structure

The schema file at [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json) declares the top-level document as an array type. Each item in this array must conform to the `exercise` definition stored within the schema's `$defs` section.

### The Root Array

At the root level, the JSON document must be an array (`"type": "array"`). Every element in this array represents a single exercise record. The schema enforces this structure through the `items` property, which references the `exercise` definition located in `$defs`.

### Reusable Definitions ($defs)

The `$defs` section contains sub-schemas that promote reusability and maintainability:

- **`languageMap`**: Maps ISO-639-1 language codes to instruction strings
- **`languageStepsMap`**: Maps language codes to ordered arrays of instruction steps
- **`steps`**: Defines an array of non-empty strings representing individual steps
- **`exercise`**: The core object definition describing a single exercise

## Core Exercise Properties

Each exercise object in the `hasaneyldrm/exercises-dataset` contains specific properties divided into categorical, instructional, anatomical, and media metadata.

### Identification and Classification

| Property | Type | Constraints |
|----------|------|-------------|
| `id` | string | Pattern `^[0-9]{4}$` (zero-padded numeric) |
| `name` | string | `minLength: 1` |
| `category` | string | `minLength: 1` (broad classification) |
| `body_part` | string | Enum of predefined values (e.g., `"back"`, `"chest"`) |
| `equipment` | string | `minLength: 1` (e.g., `"dumbbell"`, `"body weight"`) |

### Anatomical Details

- **`muscle_group`**: Primary synergist muscle group as a non-empty string
- **`secondary_muscles`**: Array of strings listing additional muscles involved
- **`target`**: Primary target muscle (e.g., `"biceps"`)

### Media and Attribution

The schema standardizes media references through pattern-validated strings:

- **`image`**: Path matching `^images/.+\.(jpg|jpeg|png)$` (180×180 thumbnail)
- **`gif_url`**: Path matching `^videos/.+\.gif$` (180×180 animation)
- **`media_id`**: Identifier of the original media asset
- **`attribution`**: Copyright notice for the media

### Temporal Metadata

- **`created_at`**: ISO-8601 timestamp with `"format": "date-time"`

## Multilingual Support via Sub-Schemas

The exercises JSON schema implements comprehensive multilingual support through reusable map structures, requiring complete translations across ten predefined languages.

### languageMap

The `languageMap` definition establishes a pattern where each key is an ISO-639-1 language code (`en`, `es`, `it`, etc.) mapping to a single instruction string. The schema requires all ten languages to be present, though additional languages are permitted.

### languageStepsMap

Similar to `languageMap`, but each language code maps to an array of strings defined by the `steps` sub-schema. This allows instructions to be stored as ordered, discrete steps per language rather than continuous text.

### Steps Definition

The `steps` sub-schema validates arrays of strings where each element represents an individual instruction step with `minLength: 1`.

## Validation Constraints

The schema enforces strict validation rules to maintain data integrity across the dataset.

### Required Fields and Closed Schema

Every exercise object must contain all defined properties as specified in the `required` array. The schema prohibits additional properties through `"additionalProperties": false`, preventing schema drift and ensuring predictable data structures.

### Pattern Matching

Specific fields utilize regular expression patterns to enforce formatting standards:
- Exercise IDs must be exactly four digits (`^[0-9]{4}$`)
- Image paths must reside in the `images/` directory with valid extensions
- GIF URLs must reside in the `videos/` directory with `.gif` extension

### Enumeration Restrictions

The `body_part` property uses an `enum` constraint to restrict values to a predefined list of anatomical regions, eliminating data entry errors and ensuring consistent categorization.

## Practical Examples

### Validating Data with Ajv (JavaScript)

```javascript
import Ajv from "ajv";
import schema from "./data/exercises.schema.json" assert { type: "json" };
import exercises from "./data/exercises.json" assert { type: "json" };

const ajv = new Ajv({ allErrors: true });
const validate = ajv.compile(schema);

if (validate(exercises)) {
  console.log("✅ Exercises data is valid!");
} else {
  console.error("❌ Validation errors:", validate.errors);
}

```

### Accessing Multilingual Instructions (Python)

```python
import json
from pathlib import Path

data_path = Path("data/exercises.json")
exercises = json.loads(data_path.read_text())

# Print the English instruction string for the first exercise

first = exercises[0]
print("English instruction:", first["instructions"]["en"])

# Print each step in Spanish

print("\nSpanish steps:")
for step in first["instruction_steps"]["es"]:
    print("- " + step)

```

### Filtering by Equipment Type (Node.js)

```javascript
const bodyWeightExercises = exercises.filter(
  e => e.equipment.toLowerCase() === "body weight"
);

console.log(`Found ${bodyWeightExercises.length} body‑weight exercises.`);

```

## Summary

- The **exercises JSON schema** resides in [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json) and defines the dataset as an array of exercise objects
- Each exercise requires **16 specific properties** including multilingual instruction maps, anatomical data, and media references
- **Multilingual support** is enforced through `languageMap` and `languageStepsMap` definitions requiring complete translations
- **Strict validation** prevents additional properties and enforces regex patterns on IDs and file paths
- The schema ensures **interoperability** for fitness applications consuming the `hasaneyldrm/exercises-dataset`

## Frequently Asked Questions

### What is the root structure of the exercises JSON schema?

The root structure is a JSON array where each element represents a single exercise. According to [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json), the root must have `"type": "array"` with items conforming to the `exercise` definition in `$defs`. This design allows the dataset to contain an arbitrary number of exercise records while maintaining uniform structure across all entries.

### How does the schema handle multiple languages?

The schema handles multilingual content through two specialized sub-schemas: `languageMap` for single-string instructions and `languageStepsMap` for ordered step arrays. Both use ISO-639-1 language codes as keys (e.g., `en`, `es`, `it`) and require all ten predefined languages to be present. This ensures every exercise has complete instructional coverage across supported languages.

### What validation rules ensure data quality?

Data quality is enforced through four mechanisms: a `required` array mandating all 16 properties, `"additionalProperties": false` preventing schema extensions, regex patterns validating the `id`, `image`, and `gif_url` formats, and an `enum` restriction on `body_part` limiting values to predefined anatomical categories. These constraints eliminate malformed entries and maintain consistency across the dataset.

### Where is the schema file located in the repository?

The schema file is located at [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json) in the `hasaneyldrm/exercises-dataset` repository. This file defines the complete structure, validation rules, and reusable sub-schemas (`languageMap`, `steps`, etc.) that govern the companion data file [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json).