# Exercises JSON Schema: Complete Structure and Field Reference for the hasaneyldrm Dataset

> Explore the exercises JSON schema from hasaneyldrm/exercises-dataset. Understand its strict structure, required fields like id and body_part, and multilingual instructions for comprehensive data validation.

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

---

**The exercises JSON schema defines a strict array-based structure where each exercise object must include multilingual instructions, media references, and validated metadata fields like `id`, `body_part`, and `equipment`, with all properties enforced as required and no additional properties allowed.**

The `hasaneyldrm/exercises-dataset` repository provides a comprehensive collection of fitness exercise data with rigorous validation standards. The exercises JSON schema located at [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json) enforces a consistent, multilingual data format that ensures every exercise record contains complete instructional text, anatomical targeting, and media references. This structured approach allows developers to safely consume the dataset across different applications and languages.

## Root Array Structure and High-Level Layout

The root of the exercises JSON document must be an array (`"type": "array"`), where each item conforms to the `exercise` definition stored in the `$defs` section. This top-level structure ensures the dataset remains a collection of discrete exercise records that can be iterated and validated as a group.

Reusable sub-schemas reside under the `$defs` key, including:

- `languageMap`: Maps ISO-639-1 language codes to instruction strings
- `languageStepsMap`: Maps language codes to arrays of instruction steps  
- `steps`: Defines the structure for ordered instruction step arrays
- `exercise`: The core object definition containing all exercise metadata

## Core Exercise Object Fields and Constraints

Each exercise object in the array must contain specific fields with strict validation rules. The schema sets `additionalProperties: false`, preventing any undocumented fields from entering the dataset.

### Identification and Categorization

Every exercise requires standardized identification fields:

- `id`: A zero-padded four-digit string matching the pattern `^[0-9]{4}$` (e.g., `"0001"`)
- `name`: Human-readable exercise name with `minLength: 1`
- `category`: Broad classification string mirroring the body part focus
- `body_part`: Targeted anatomical region restricted to a predefined `enum` list (e.g., `"back"`, `"chest"`, `"shoulders"`)
- `equipment`: Required equipment string (e.g., `"dumbbell"`, `"body weight"`) with `minLength: 1`

### Anatomical Targeting

Muscle-specific fields provide detailed anatomical context:

- `target`: Primary target muscle (e.g., `"biceps"`, `"quadriceps"`) with `minLength: 1`
- `muscle_group`: Primary synergist muscle group with `minLength: 1`
- `secondary_muscles`: Array of additional muscles involved, where each item must have `minLength: 1`

### Multimedia and Attribution

Media references follow strict path patterns to ensure file organization:

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

### Temporal Metadata

The `created_at` field stores the exercise creation timestamp as an ISO-8601 formatted string with `"format": "date-time"` validation.

## Multilingual Instruction Schemas

The exercises JSON schema enforces comprehensive multilingual support through two specialized sub-schema definitions that ensure every exercise provides complete instructions across languages.

### languageMap for Single-String Instructions

The `languageMap` definition requires an object with ISO-639-1 language codes (such as `en`, `es`, `it`) as keys. Each key maps to a single instruction string with `minLength: 1`. The schema mandates that exactly ten languages must be present, though additional languages are permitted beyond this required set.

### languageStepsMap for Step-by-Step Instructions

The `languageStepsMap` follows the same language code structure but maps to the `steps` sub-schema—an array of non-empty strings representing ordered instruction steps. This allows applications to display instructions as numbered lists or individual steps rather than continuous text.

## Validation Guarantees and Constraints

The exercises JSON schema implements several strict validation mechanisms to maintain data integrity:

- **Required fields**: The `required` array lists every property that must be present; missing any field causes validation failure
- **Pattern validation**: Regular expressions enforce formatting standards for `id`, `image`, and `gif_url` fields
- **Enum restrictions**: The `body_part` field accepts only predefined values, preventing typographical errors in categorization
- **Type safety**: Each field enforces specific JSON Schema types (string, array, object) with additional format constraints for dates and patterns

## Practical Code Examples

### Validating Data with AJV

Use the AJV library to validate the exercises array against the schema before processing:

```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);
}

```

### Querying Multilingual Content in Python

Access specific language instructions using standard dictionary lookups:

```python
import json
from pathlib import Path

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

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

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

```

### Filtering Exercises by Equipment

Filter the dataset to find exercises requiring specific equipment:

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

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

```

## Summary

The exercises JSON schema in `hasaneyldrm/exercises-dataset` provides a robust framework for fitness data standardization:

- The root document must be an array containing exercise objects validated against strict schema definitions
- Every exercise requires complete multilingual instruction sets via `languageMap` and `languageStepsMap` sub-schemas
- Field-level constraints include pattern matching for IDs and file paths, enum restrictions for body parts, and mandatory attribution metadata
- The `additionalProperties: false` setting ensures no extraneous data enters the dataset, maintaining downstream compatibility

## Frequently Asked Questions

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

The schema file resides at [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json) in the repository root. This file contains the complete JSON Schema definition that validates the structure found in [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json).

### What languages are required for the multilingual instruction fields?

The `languageMap` and `languageStepsMap` definitions require exactly ten ISO-639-1 language codes to be present (such as `en` for English, `es` for Spanish, and `it` for Italian). While these ten languages are mandatory, the schema permits additional languages beyond this minimum requirement.

### How does the schema validate image and video file paths?

The schema applies regular expression patterns to ensure consistent file organization: the `image` field must match `^images/.+\.(jpg|jpeg|png)$` and the `gif_url` field must match `^videos/.+\.gif$`. These patterns enforce that media files reside in the correct directories with appropriate extensions.

### Can I add custom fields to exercise objects?

No, the exercise object definition sets `additionalProperties: false`, which prevents validation from succeeding if any properties outside the defined schema are present. All custom data must either conform to existing fields or be stored in a separate metadata structure.