course-spec

An open format for keeping a complete online course in one directory under version control: the outline, HTML slide decks with narration, translations, quizzes with answer keys, and a record of what has been published. People and AI agents write it by hand; tools check it, record it to video, and import it into a learning platform.

This repository holds the Go types, a loader, a validator, generated JSON Schemas, and the coursespec command.

Install

go install github.com/academyosio/course-spec/cmd/coursespec@latest

Commands

coursespec validate <dir>      # check a course; exits non-zero on errors
coursespec lessons <dir>       # list sections, lessons, and quizzes with publish status
coursespec schema [name]       # print a JSON Schema: course, section, quiz, published

Given a directory without a course.json, validate and lessons act on every course beneath it. Add --format json for tools and agents.

Each finding names the file, a JSON pointer or slide, the problem, and a fix:

error: sections/01-designing-endpoints/section.json /lessons/2/id: lesson "pagination" is not in the deck [lesson-not-in-deck]
  fix: use the data-id of a slide with data-lesson, or set "type": "text" for a text lesson

A Course Directory

<course>/
  course.json                    course manifest
  pronunciations.json            how narration says terms (optional)
  published.json                 written by tools after publishing
  theme/                         shared deck CSS, JS, fonts (optional)
  sections/
    01-<slug>/
      section.json               section manifest
      deck/index.html            slides with narration
      deck/voiceover/transcript.json   translations (optional)
      quiz.json                  quiz with answer key (optional)

Every file is JSON with camelCase property names. A complete example is in testdata/courses/web-apis.

Decks

A deck is an HTML page. Each slide is an element with class slide and a stable data-id; narration is in data-vo or a child aside class="notes"; a slide with data-lesson starts a lesson, whose ID is that slide's data-id. These are the videoascode conventions, so the same deck can be recorded to video.

A deck is self-contained: it loads styles, scripts, fonts, and images from the course directory or its theme by relative paths. Players that sandbox decks block remote files, so the validator warns about them.

Translations

Narration in other languages is in deck/voiceover/transcript.json, in the videoascode transcript format. Each slide entry carries id, the slide's data-id, so translations stay with their slides when slides are added or removed.

Published State and Fingerprints

Tools write published.json after recording or importing a course. For each lesson it records a content fingerprint: a hash of the lesson's slides and narration in every language. coursespec lessons compares fingerprints to report what changed since publishing, even in a fresh clone.

Library

c, err := coursespec.Load("courses/building-web-apis")   // stops at the first problem
findings := validate.Course("courses/building-web-apis", validate.Options{})
report := c.Status()                                       // lessons and quizzes with status

Package	Purpose
coursespec	Types for every file, Load, Find, and publish status
deck	Slides, lessons, transcripts, and content fingerprints from HTML decks
validate	Every check, as findings with a fix
schema	The generated JSON Schemas, embedded

The Go types are the source of truth. After changing them, regenerate the schemas with go generate ./schema.

Documentation

Guides for the format, validation, AI agents, and the Go library are in docs/, a MkDocs site: pip install mkdocs-material, then mkdocs serve. Start with Getting started.

Changes are in CHANGELOG.md, generated from CHANGELOG.json, and release notes in docs/releases/.

Specification

The requirements, design, plan, and roadmap are in docs/specs/initiatives/INIT-COURSESPEC-001.

License

MIT