The Problem

Curriculum designers and ed‑tech platforms need a single, machine‑readable source that captures what children should learn, how concepts depend on each other, and how those concepts map to official standards. Existing datasets are either flat lists or locked inside proprietary products, making it hard to build adaptive learning pathways or cross‑curriculum analytics.

What This Does

The repository ships a fully‑specified learning taxonomy as pure JSON data:

  • data/topics.json – 1,590 micro‑topic nodes, each with id, type, subject, ageRange, evidence, assessmentPrompt, and standards links.
  • data/dependencies.json – 3,221 directed edges (topicId → prerequisiteId) with a strength flag and a human‑readable reason.
  • data/curriculum-standards.json – the source standards (NGSS, Common Core, UK NC, etc.) keyed by <curriculum>:<code>.
  • data/clusters.json – 183 parent‑friendly domain summaries.
  • schema/*.schema.json – JSON‑Schema definitions for each data file, ensuring structural integrity.

A single helper script (scripts/validate.mjs) validates the JSON payloads against the schemas, guaranteeing that the published taxonomy remains internally consistent.

How It Is Wired

Execution starts at scripts/validate.mjs. The script:

  1. Imports Node’s fs/path modules and a JSON‑Schema validator (e.g., ajv).
  2. Loads each schema from schema/ and each data file from data/.
  3. Runs validation loops (schema.validate(data)) and reports any mismatches.

No other code paths exist; the repository contains no server, UI, or build steps. The import graph consists of a single internal module (the script itself), with 0 import edges and 0 circular dependencies, confirming that the validation logic is isolated. The script’s 74 lines contain 24 branch points, a medium‑severity cognitive‑load issue flagged by static analysis; refactoring into smaller validator functions would improve readability.

How To Use It

# 1. Clone the repo
git clone https://github.com/moses-y/os-taxonomy
cd os-taxonomy

# 2. Install Node dependencies (package.json defines them)
npm install   # creates a lockfile if you follow the health recommendation

# 3. Run the validator
node scripts/validate.mjs

The command prints validation results; a clean run indicates that all JSON files conform to their respective schemas. No environment variables or external services are required.

Real‑World Use

An adaptive learning engine can ingest data/topics.json and data/dependencies.json to construct prerequisite‑aware learning paths. For example, a backend service might:

import topics from './data/topics.json';
import deps   from './data/dependencies.json';

function unlockableTopics(completedIds) {
  return topics.filter(t => 
    deps.filter(d => d.topicId === t.id)
        .every(d => completedIds.includes(d.prerequisiteId))
  );
}

This yields the set of concepts a learner is ready to tackle next, enabling personalized curricula or progress dashboards.

Code Health & Issues

  • High – Missing lockfile – package.json present, no package-lock.json/pnpm-lock.yaml. → Run npm install and commit the generated lockfile.
  • Medium – Dependabot not configured – No .github/dependabot.yml. → Add a Dependabot config to keep dependencies patched.
  • Medium – Cognitive load in scripts/validate.mjs – 24 branches in 74 lines. → Split validation steps into dedicated functions or a strategy table.
  • Medium – No test suite – No test/ directory or test files. → Add unit tests for schema validation.
  • Medium – No CI pipeline – No .github/workflows/ or other CI config. → Implement a simple GitHub Actions workflow that runs npm ci && node scripts/validate.mjs.

All findings are derived from deterministic static analysis; no additional issues were inferred.

The Bottom Line

The repo delivers a high‑quality, standards‑aligned learning taxonomy in a straightforward, data‑only format, ready for integration into curriculum analytics or adaptive learning platforms. Its main limitations are the lack of a lockfile, automated testing, and CI, which together raise maintenance risk. Engineers looking to build on this dataset should first lock the dependency tree and add basic validation tests before extending the taxonomy.