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

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

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:

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:

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 in the repository root. This file contains the complete JSON Schema definition that validates the structure found in 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.

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