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

> Discover the purpose of exercises.schema.json. Understand how this JSON Schema validates fitness exercise data, ensuring structure, types, and multilingual content for the hasaneyldrm/exercises-dataset.

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

---

**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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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:

```javascript
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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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:

```python
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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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:

```yaml
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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/exercises.schema.json).

## Summary

- **exercises.schema.json** is the canonical JSON Schema located at [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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.