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

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.

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

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)

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)

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

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