Project layout - Asakiri Docs

Canonical format, version 1. Validate against the published JSON Schemas rather than reimplementing the parser.

A course is a single project folder. One project.json manifest at the root names every collection, asset, and lesson by a project-relative path, and defines the outline.

Directory tree

japanese-starter/
├─ project.json                       manifest: metadata, file lists, outline
├─ content/
│  ├─ collections/
│  │  ├─ vocabulary.json              a collection (fields + record file list)
│  │  └─ hiragana.json
│  └─ records/
│     ├─ cat.json                     one record per file
│     ├─ dog.json
│     └─ hiragana/
│        ├─ a.json
│        └─ ha.json
├─ media/
│  └─ assets/
│     └─ cat-image/
│        ├─ asset.json                asset metadata
│        └─ original.svg              the binary file
└─ lessons/
   └─ meet-neko/
      ├─ lesson.json                  lesson: ordered parts, each pointing at a file
      └─ parts/
         ├─ intro/document.json       a Tiptap rich-text part
         ├─ in-media/composition.json a rich-media part
         └─ choose/exercise.json      an exercise part

Paths in project.json are relative to the project root. Paths inside a collection file (its recordFiles) are relative to that collection file, so content/collections/vocabulary.json references records with "../records/cat.json".

project.json

{
  "format": "asakiri-course",
  "formatVersion": 1,
  "project": {
    "id": "course_japanese_starter",
    "title": "Japanese Starter",
    "description": "A small fixture showing reusable content across lessons and every exercise type.",
    "defaultLocale": "en",
    "learningLocales": ["ja"]
  },
  "collections": ["content/collections/vocabulary.json", "content/collections/hiragana.json"],
  "assets": [
    "media/assets/cat-image/asset.json",
    "media/assets/cat-ja-audio/asset.json"
  ],
  "lessons": [
    "lessons/meet-neko/lesson.json",
    "lessons/practice-neko/lesson.json"
  ],
  "outline": [
    {
      "id": "section_getting_started",
      "title": "Getting started",
      "lessonIds": ["lesson_meet_neko", "lesson_practice_neko"]
    }
  ]
}

Field	Meaning
`format`, `formatVersion`	Always `"asakiri-course"` and an integer version. Every file in the project carries them, not just the manifest.
`project`	Course metadata. `defaultLocale` and `learningLocales` drive locale handling.
`collections`, `assets`, `lessons`	Project-relative paths to each entity file.
`outline`	Ordered sections, each with a `title` and an ordered `lessonIds` list. The outline is the course structure; the `lessons` list is just where to load them from.

The parsed in-memory CourseProject (see Reader and writer) carries more optional fields than the fixture writes, such as level, license, contributors, funding, sponsors, and coverAssetId. The fixture keeps the manifest minimal; a real course may populate more. Read defensively and treat extra fields as optional.

Loading order

Read and parse project.json. Reject an unknown format; refuse a formatVersion higher than you support, and upgrade one lower than yours (see File formats).
Load each collection file, then its recordFiles.
Load each asset file.
Load each lesson file, then each part file it references.
Build the in-memory course and a binding resolver (see Resolving and rendering).