Curriculum structure basics

A curriculum in apprenti.dev is not a database record — it is a folder of files that the app already knows how to read. Understanding that layout is the first step to authoring one, whether by hand or with apprenti creator.

JSON for structure, Markdown for narrative

Structured content — metadata, ordering, references, policies — is JSON. Long-form content — task instructions, a resource's writeup — is Markdown. Every durable structured object carries: 

{
  "schemaVersion": 1,
  "id": "stable-id"
}

The id is permanent and independent of file paths — a task can move between modules or terms without ever changing identity. Never derive an id from a path, and never let the two disagree.

One curriculum (the common case) 

/
  curriculum.json
  curriculum/
    year-1/
      term-1/
        term.json
        <module>/
          <task-id>/
            task.json
            instructions.md
  resources/
    <resource-id>.json
  competencies/
    <competency-id>.json
  schemas/
    *.schema.json

The term file holds the ordered list of task ids for that term — that ordering, not folder or filename sort order, is what the app treats as the academic path.

Several curricula in one repository

The canonical, official repository holds more than one apprenticeship path side by side: 

/
  curricula.json
  curricula/
    software-engineering/
      curriculum.json
      curriculum/...
    data-analytics-ai/
      curriculum.json
      curriculum/...
  resources/          # shared library, referenced by id from any curriculum
  competencies/
  schemas/

Individual resource and competency files live once at the repository root and are shared by every curriculum in that working copy by id — a nested copy with the same id inside one curriculum's own folder is an explicit override, not a second library. Duplicating the same content in both places is a bug, not a feature.

This also changes where an apprentice's or mentor's own personal-data folder lives. For a repository with a single root manifest, it's the folder you'd expect — the apprentice's own folder, the mentor's own folder. For a nested curriculum inside a multi-curriculum repository, both get an extra segment identifying which curriculum the data belongs to, so the same apprentice working through two curricula in one fork doesn't mix their task state between them. Their profile is the one exception — it lives once, at the person level, shared across every curriculum they work through in that fork, not duplicated per curriculum.

The reference curriculum

The first official path is the Software Engineering apprenticeship — currently 54 tasks across 11 terms, hosted in the curricula catalog. Treat it as the reference for scale and structure: if a change to the format can't cleanly describe that curriculum, the format needs revisiting, not the curriculum.

Personal overlays are not curriculum

The apprentice and mentor personal-data folders hold records for a specific pair — profile, task state, reflections, reviews. They live inside the same working copy but are never part of the shareable curriculum, and a curriculum-authoring tool should never write to them.

← All Docs Back to apprenti.dev