# How to Integrate the TypeScript Interface for Dataset Access in hasaneyldrm/exercises-dataset

> Integrate the TypeScript interface for dataset access in hasaneyldrm/exercises-dataset. Achieve type safety when accessing multilingual exercise data with JSON module resolution.

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

---

**Import the JSON data from [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json), cast it to the `Exercise[]` type defined in the README, and enable `resolveJsonModule` in your [`tsconfig.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/tsconfig.json) to achieve full compile-time type safety when accessing the multilingual exercise dataset.**

The hasaneyldrm/exercises-dataset repository provides a comprehensive catalogue of fitness exercises stored in a structured JSON format. To integrate the TypeScript interface for dataset access, you import the data file and apply the `Exercise` interface documented in [`README.md`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/README.md) at lines 998–1036. This method provides IntelliSense autocomplete and compile-time validation for all properties including nested multilingual instruction objects.

## Understanding the Dataset Structure

The raw dataset resides in **[`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json)**, which exports a JSON array where each element conforms to the `Exercise` interface schema. According to the hasaneyldrm/exercises-dataset source code, the interface defines primitive fields including `id`, `name`, `category`, `body_part`, `equipment`, `muscle_group`, `target`, `media_id`, `image`, `gif_url`, `attribution`, and `created_at`.

The schema also contains complex nested structures for internationalization:
- **`instructions`**: An object with string properties for ten languages (`en`, `es`, `it`, `tr`, `ru`, `zh`, `hi`, `pl`, `ko`, `fr`)
- **`instruction_steps`**: A parallel object where each language maps to a string array
- **`secondary_muscles`**: A string array listing additional muscle groups targeted by the exercise

## Configuring TypeScript for JSON Imports

Before integrating the interface, ensure your TypeScript compiler can resolve JSON modules. Create or update your [`tsconfig.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/tsconfig.json) to include these compiler options:

```json
{
  "compilerOptions": {
    "resolveJsonModule": true,
    "esModuleInterop": true,
    "strict": true
  }
}

```

The **`resolveJsonModule`** flag allows direct imports of `.json` files with type inference, while **`esModuleInterop`** ensures compatibility between CommonJS and ES module formats when loading the dataset.

## Implementing the TypeScript Integration

Follow this workflow to integrate the TypeScript interface for dataset access in your application.

### Import the Dataset and Interface

First, import the exercise data and define the `Exercise` interface in your TypeScript file. The interface declaration mirrors the schema documented in the repository's [`README.md`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/README.md):

```typescript
import exercises from "./data/exercises.json";

interface Exercise {
  id: string;
  name: string;
  category: string;
  body_part: string;
  equipment: string;
  instructions: {
    en: string;
    es: string;
    it: string;
    tr: string;
    ru: string;
    zh: string;
    hi: string;
    pl: string;
    ko: string;
    fr: string;
  };
  instruction_steps: {
    en: string[];
    es: string[];
    it: string[];
    tr: string[];
    ru: string[];
    zh: string[];
    hi: string[];
    pl: string[];
    ko: string[];
    fr: string[];
  };
  muscle_group: string;
  secondary_muscles: string[];
  target: string;
  media_id: string;
  image: string;
  gif_url: string;
  attribution: string;
  created_at: string;
}

```

### Type Assertion and Basic Queries

Cast the imported JSON to the `Exercise[]` type to enable full type safety. This assertion tells the TypeScript compiler to treat the raw JSON data as an array of `Exercise` objects:

```typescript
const data = exercises as Exercise[];

// Filter with type-safe property access
const bodyweight = data.filter(ex => ex.equipment === "body weight");
console.log(`Found ${bodyweight.length} body-weight exercises`);

```

### Accessing Multilingual Content

Use dot notation to access language-specific instructions. The nested structure provides type-safe access to each supported language without runtime guesswork:

```typescript
function getEnglishInstruction(id: string): string | undefined {
  const ex = data.find(e => e.id === id);
  return ex?.instructions.en;
}

// Retrieve step-by-step instructions for Turkish users
const turkishSteps = data[0].instruction_steps.tr;

```

### Advanced Data Operations

Leverage TypeScript's type inference when transforming the dataset. The compiler validates property access in array methods like `filter`, `map`, and `reduce`:

```typescript
// Build a random workout with compile-time validation
const randomWorkout = data
  .sort(() => Math.random() - 0.5)
  .slice(0, 6)
  .map(e => `${e.name} (${e.target})`);

// Group exercises by muscle group with proper typing
const byMuscle = data.reduce<Record<string, Exercise[]>>((acc, ex) => {
  acc[ex.muscle_group] = acc[ex.muscle_group] ?? [];
  acc[ex.muscle_group].push(ex);
  return acc;
}, {});

```

## Working with the Exercise Interface

The **`Exercise`** interface serves as a **self-documenting contract** between the dataset and your application logic. By implementing this interface, you ensure that any consumer—whether frontend components, backend APIs, or data processing scripts—can safely access properties without runtime errors.

When integrating the TypeScript interface for dataset access, remember that the `secondary_muscles` field is typed as `string[]` and the `created_at` field follows ISO 8601 formatting as a string. The multilingual objects ensure your application can serve content in English, Spanish, Italian, Turkish, Russian, Chinese, Hindi, Polish, Korean, or French with full type safety.

## Summary

- **Import path**: Load the dataset from [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json) using ES6 import syntax after enabling `resolveJsonModule` and `esModuleInterop` in [`tsconfig.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/tsconfig.json)
- **Type definition**: The `Exercise` interface is defined in [`README.md`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/README.md) lines 998–1036 and provides complete type coverage for all JSON properties including nested multilingual fields
- **Type safety**: Cast imported data to `Exercise[]` to enable compile-time checking for property names, data types, and language codes
- **Multilingual access**: Reference ten languages through the `instructions` and `instruction_steps` nested objects using standard dot notation (e.g., `ex.instructions.es`, `ex.instruction_steps.fr`)
- **Zero dependencies**: The dataset requires no external packages—only standard TypeScript JSON module resolution

## Frequently Asked Questions

### Where is the Exercise interface defined in the repository?

The `Exercise` interface is documented in the **[`README.md`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/README.md)** file at lines 998–1036 of the hasaneyldrm/exercises-dataset repository. This definition includes all primitive fields, nested multilingual objects, and array types that mirror the structure of [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json).

### Do I need to install any npm packages to use this dataset?

No. The hasaneyldrm/exercises-dataset repository contains no external dependencies. You only need TypeScript configured with `resolveJsonModule: true` in your [`tsconfig.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/tsconfig.json) to import the JSON file directly and apply the interface type definitions.

### How do I handle missing or optional fields in the Exercise interface?

While the interface defines `secondary_muscles` as `string[]`, you should use optional chaining (`?.`) when accessing potentially undefined nested properties. The TypeScript compiler will enforce that you check for property existence before accessing multilingual instruction fields.

### Can I use this interface in a JavaScript project without TypeScript?

Yes, you can use the [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json) file in JavaScript, but you will lose compile-time type safety. The interface serves as documentation for the expected schema. JavaScript consumers should manually validate the data structure or use runtime validation libraries like Zod that match the `Exercise` interface shape.