How to Extend the Exercises Dataset with Custom Exercise Fields

To extend the exercises dataset with custom exercises, you must update the JSON Schema definition in data/exercises.schema.json to declare the new property, then populate the field in data/exercises.json while maintaining strict validation compliance.

The hasaneyldrm/exercises-dataset repository uses a strict JSON Schema to ensure data consistency across all exercise records. Because the schema enforces "additionalProperties": false, any custom field you add to the dataset must be explicitly defined in the schema first, or validation will fail.

Understanding the Schema Validation Constraint

The repository maintains data integrity through a rigid validation layer defined in data/exercises.schema.json. This file controls exactly which properties are permitted for each exercise object.

The critical setting is "additionalProperties": false at the root of the exercise object definition. This directive instructs validators to reject any properties not explicitly listed in the schema. Therefore, you cannot simply append new fields to data/exercises.json without first registering them in the schema file.

Step-by-Step Guide to Adding Custom Fields

Locate and Modify the Schema

Open data/exercises.schema.json in your editor. Navigate to the "properties" block within the exercise object definition. This section enumerates every valid field currently supported by the dataset.

Define the New Property

Insert your custom field definition inside the "properties" object. Specify the type, description, and any constraints such as enum values or format patterns.

If the field should be mandatory for every exercise, add the field name to the "required" array. If it is optional, omit it from this array.

{
  "type": "object",
  "properties": {
    "id": { "type": "string" },
    "name": { "type": "string" },
    "difficulty": {
      "type": "string",
      "description": "Relative difficulty level",
      "enum": ["beginner", "intermediate", "advanced"]
    }
  },
  "required": ["id", "name"],
  "additionalProperties": false
}

Update the Dataset Records

Open data/exercises.json and add the new field to any exercise objects that require it. Ensure the value conforms to the type constraints defined in your schema update.

{
  "id": "0001",
  "name": "3/4 sit-up",
  "difficulty": "beginner",
  "created_at": "2026-03-18T12:31:32.854798+00:00",
  "attribution": "© Gym visual — https://gymvisual.com/"
}

Validate Your Changes

Run a JSON Schema validator against the modified files to confirm compliance. Tools like AJV (JavaScript), jsonschema (Python), or online validators can verify that your updated exercises.json conforms to the modified exercises.schema.json.

Practical Example: Adding a Difficulty Rating

Here is a complete workflow for adding an optional difficulty field to the dataset.

First, update the schema in data/exercises.schema.json:

"difficulty": {
  "type": "string",
  "description": "Relative difficulty level (e.g., \"beginner\", \"intermediate\", \"advanced\").",
  "enum": ["beginner", "intermediate", "advanced"]
}

Leave "difficulty" out of the "required" array to keep it optional. Then append the field to specific exercises in data/exercises.json:

{
  "id": "0421",
  "name": "Barbell Squat",
  "difficulty": "intermediate",
  "created_at": "2026-03-18T12:31:32.854798+00:00"
}

Summary

• Schema First: Always define new properties in data/exercises.schema.json before adding them to the dataset.
• Strict Validation: The "additionalProperties": false setting prevents undocumented fields from being accepted.
• Optional vs Required: Add field names to the "required" array only if every exercise must contain the data.
• Data Location: Exercise records are stored in data/exercises.json, while validation rules live in data/exercises.schema.json.
• Validation Tools: Use standard JSON Schema validators to verify dataset integrity after modifications.

Frequently Asked Questions

What happens if I add a field without updating the schema?

If you add a property to data/exercises.json without declaring it in data/exercises.schema.json, validation will fail due to the "additionalProperties": false constraint. The dataset will be considered invalid because the schema explicitly forbids undocumented properties.

Can I make custom fields optional or required?

Yes. To make a field optional, define it in the schema's "properties" section but exclude it from the "required" array. To make it mandatory, include the field name in the "required" array, which forces every exercise object to contain that property.

How do I validate the dataset after modifications?

Use any JSON Schema validation library compatible with draft-07 or later, such as AJV for Node.js, jsonschema for Python, or check-jsonschema as a command-line tool. Point the validator to data/exercises.schema.json and validate data/exercises.json against it.

Where is the exercise data actually stored?

All exercise records are stored in data/exercises.json. The validation rules and allowed property definitions are maintained separately in data/exercises.schema.json, which acts as the single source of truth for dataset structure according to the hasaneyldrm/exercises-dataset repository structure.

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