# How to Extend the Exercises Dataset with Custom Exercise Fields

> Extend the exercises dataset with custom exercise fields. Update the JSON Schema and populate your data while ensuring strict validation for the hasaneyldrm/exercises-dataset repository.

- Repository: [Hasan Emir Yıldırım/exercises-dataset](https://github.com/hasaneyldrm/exercises-dataset)
- Tags: how-to-guide
- Published: 2026-07-31

---

**To extend the exercises dataset with custom exercises, you must update the JSON Schema definition in [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json) to declare the new property, then populate the field in [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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.

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

```json
{
  "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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/exercises.json) conforms to the modified [`exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json):

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

```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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json), while validation rules live in [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json) without declaring it in [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json) and validate [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json) against it.

### Where is the exercise data actually stored?

All exercise records are stored in [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json). The validation rules and allowed property definitions are maintained separately in [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json), which acts as the single source of truth for dataset structure according to the `hasaneyldrm/exercises-dataset` repository structure.