Skip to content

Add CI workflow to validate the exercise dataset#57

Open
Mavi9412 wants to merge 1 commit into
hasaneyldrm:mainfrom
Mavi9412:ci/validate-dataset
Open

Add CI workflow to validate the exercise dataset#57
Mavi9412 wants to merge 1 commit into
hasaneyldrm:mainfrom
Mavi9412:ci/validate-dataset

Conversation

@Mavi9412

@Mavi9412 Mavi9412 commented Jul 16, 2026

Copy link
Copy Markdown

Summary

This repo currently has no automation at all — every data or translation PR is merged on trust. This adds a single GitHub Actions workflow that validates data/exercises.json on every PR and push to main, covering five checks:

  • JSON Schema validationdata/exercises.json against data/exercises.schema.json (draft 2020-12, via ajv)
  • No duplicate ids
  • Every image path resolves to a real file
  • Every gif_url path resolves to a real file
  • index.html's embedded copy of the dataset stays in sync with data/exercises.jsonindex.html inlines the full dataset as a JS literal for offline use; today it's byte-identical to data/exercises.json, but nothing currently stops that from silently drifting on a future data PR

The workflow installs ajv/ajv-formats at CI time (npm install --no-save) rather than committing a package.json/lockfile, to keep the repo's zero-build, "just open the HTML files" design intact.

Why

The last several merged PRs in this repo's history are contributors adding new-language instructions (French, Hindi, Polish, Korean...). That pattern is exactly where an unenforced schema causes real friction — daceea8 is a follow-up commit fixing the JSON Schema's language maps after a language PR had already been merged once. This workflow would have caught that at review time instead of needing a second commit.

Design notes

  • The index.html sync check parses the embedded array with a small bracket-depth scanner rather than a fixed regex, so it keeps working whether the array is minified or reformatted to multi-line JSON later.
  • Parse/compile failures (a malformed exercises.json, a broken schema) are caught and reported as a clear ✗ message, not a raw stack trace — since a JSON syntax slip is the most likely mistake for a contributor hand-editing a ~150k-line file, and it deserves the clearest error of anything this workflow checks.
  • push is restricted to branches: [main] and pull_request covers incoming PRs (including forks), so a PR from a branch in this repo doesn't trigger the workflow twice for the same commit.
  • permissions: contents: read and timeout-minutes: 5 are set explicitly — the job only reads the repo and doesn't need more than that.

Test plan

Verified locally by deliberately breaking each check one at a time against the real dataset and confirming a correct failure, then restoring:

  • Valid dataset passes all five checks
  • A duplicate id is caught
  • A missing image file is caught
  • A missing gif_url file is caught
  • A schema violation (bad body_part enum, missing required language) is caught
  • index.html going out of sync with data/exercises.json is caught
  • Malformed JSON in data/exercises.json produces a clean error, not a stack trace
  • A broken schema (invalid keyword) produces a clean error, not a stack trace
  • A record missing image/gif_url entirely reports a clear message instead of "missing image file \"undefined\""
  • The workflow YAML parses correctly and the push/pull_request path list stays in sync via a YAML anchor

Adds a GitHub Actions workflow that runs on every PR and push to main
touching the dataset, checking:

- data/exercises.json validates against data/exercises.schema.json
  (JSON Schema draft 2020-12, via ajv)
- no duplicate exercise ids
- every image and gif_url path resolves to a real file
- index.html's embedded copy of the dataset stays in sync with
  data/exercises.json

None of this was previously enforced, so a future data or translation
PR could silently break the schema, reference a missing media file,
or leave index.html out of sync with the source data.

The validation script fails with a clear message rather than a raw
stack trace on malformed JSON, a broken schema, or missing required
fields, since those are the most likely mistakes for a contributor
hand-editing a large JSON file.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant