What Is exercises.schema.json? Purpose and Validation Rules Explained

exercises.schema.json defines the canonical JSON Schema that validates the structure, data types, and multilingual requirements for the fitness exercise dataset stored in data/exercises.json.

The hasaneyldrm/exercises-dataset repository maintains a structured collection of fitness exercises consumed by applications like Instagit. The exercises.schema.json file serves as the authoritative contract that guarantees data consistency, enforces required fields, and supports internationalization across the entire codebase.

Core Responsibilities of exercises.schema.json

Data Validation and Type Safety

At its foundation, exercises.schema.json ensures every record in data/exercises.json adheres to a strict contract. The schema defines required fields such as id, name, category, image, gif_url, and created_at, and enforces specific data types and patterns. For example, the id field must match the regular expression ^[0-9]{4}$, ensuring zero-padded four-digit identifiers (Lines 51‑58 and 90‑138). This prevents malformed entries from entering the dataset and breaking downstream consumers.

Multilingual Support Architecture

The schema provides reusable sub-schemas to handle internationalization. The languageMap definition (Lines 11‑27) enforces that every exercise includes translation strings for all supported ISO‑639‑1 language codes (e.g., en, es, it). Similarly, languageStepsMap (Lines 29‑45) guarantees that step-by-step instructions exist as arrays of non-empty strings for each language. This structure ensures that frontend applications can reliably render content in multiple languages without encountering missing keys.

Preventing Schema Drift

To maintain long-term stability, the schema explicitly forbids unplanned properties. The setting "additionalProperties": false (Line 156) ensures that only declared fields exist within each exercise object. This prevents accidental data drift and forces developers to update the schema explicitly when introducing new attributes, maintaining versioning clarity across the ecosystem.

Key Schema Definitions in exercises.schema.json

Root Structure and Exercise Objects

The root of exercises.schema.json defines the dataset as an array, with each element referencing #/$defs/exercise (Lines 6‑9). This structure allows the validator to iterate over the entire collection while applying the same strict object definition to every entry. The schema conforms to JSON Schema Draft 2020‑12, as declared by the $schema property, ensuring compatibility with modern validation tools.

Strict Property Constraints

Each exercise object must contain a specific set of properties with precise constraints. Beyond the required fields, the schema defines formats such as date-time for temporal data and URI patterns for media references. These constraints are centralized in the $defs/exercise definition, making the schema self-documenting—developers can read the file to understand the exact shape of valid data without inspecting raw JSON samples.

How to Validate Data Against exercises.schema.json

Validating with Node.js and AJV

Use the AJV library to validate the dataset directly against the schema in a Node.js environment:

import Ajv from "ajv";
import addFormats from "ajv-formats";
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 });
addFormats(ajv);                     // supports date-time format
const validate = ajv.compile(schema);

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

This approach leverages the Draft 2020‑12 specification declared in exercises.schema.json to catch type mismatches, missing required fields, and pattern violations in a single pass.

Validating with Python and jsonschema

For Python-based data pipelines, use the jsonschema library with Draft 2020‑12 support:

import json
from jsonschema import Draft202012Validator, RefResolver

# Load files

with open("data/exercises.schema.json") as f:
    schema = json.load(f)

with open("data/exercises.json") as f:
    data = json.load(f)

# Create validator (draft-2020-12)

resolver = RefResolver.from_schema(schema)
validator = Draft202012Validator(schema, resolver=resolver)

errors = sorted(validator.iter_errors(data), key=lambda e: e.path)
if not errors:
    print("✅ exercises.json conforms to the schema")
else:
    print("❌ Validation errors:")
    for err in errors:
        print(f"- {list(err.path)}: {err.message}")

The RefResolver handles internal references within exercises.schema.json, such as the $defs used by languageMap and languageStepsMap.

Automating Checks in CI/CD Pipelines

Integrate validation into GitHub Actions to prevent invalid data from merging into the main branch:

name: Validate Exercise Dataset
on: [push, pull_request]

jobs:
  json-schema:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Node & AJV
        run: |
          npm ci
          npm i -g ajv-cli
      - name: Validate JSON
        run: |
          ajv validate -s data/exercises.schema.json -d data/exercises.json

This pipeline fails automatically if any commit introduces exercise records that violate the constraints defined in exercises.schema.json.

Summary

• exercises.schema.json is the canonical JSON Schema located at data/exercises.schema.json that defines validation rules for the exercise dataset.
• It enforces strict typing, required fields, and multilingual support through reusable sub-schemas like languageMap and languageStepsMap.
• The schema prevents data drift by setting additionalProperties to false, ensuring only declared fields exist in data/exercises.json.
• It supports Draft 2020‑12 validators in JavaScript, Python, and CI/CD environments, making the dataset machine-readable and safe to consume across the Instagit ecosystem.

Frequently Asked Questions

What is the purpose of exercises.schema.json?

exercises.schema.json serves as the master validation contract for the fitness exercise dataset. It guarantees that every entry in data/exercises.json contains the required fields, follows specific data patterns like four-digit zero-padded IDs, and includes complete translations for all supported languages.

How does exercises.schema.json handle multiple languages?

The schema defines languageMap and languageStepsMap sub-schemas (Lines 11‑45) that require a string value for every ISO‑639‑1 language code. This ensures that properties like instructions and step-by-step guides exist for every supported language, preventing incomplete localization in the dataset.

What happens if I add extra fields to an exercise object?

The schema explicitly sets "additionalProperties": false (Line 156), which causes validation to fail if any undeclared properties are present. This constraint forces schema updates to be explicit and documented, protecting downstream applications from unexpected data structures.

Which tools can validate against exercises.schema.json?

Any tool supporting JSON Schema Draft 2020‑12 can validate the dataset. Popular options include AJV for Node.js, jsonschema for Python, and command-line utilities like ajv-cli for integration into CI/CD pipelines such as GitHub Actions.

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