Skip to content

Modular Curriculum Format (MCF) 1.0

Status

This document defines MCF 1.0. MCF is a source-format standard. It does not prescribe compiler language, generated HTML, CSS, runtime architecture, learner storage, accounts, badges, or certificates.

The words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY indicate requirement levels.

1. Purpose

MCF is an open, human-readable format for complete courses. Independent readers and writers can use the same course source while presenting it in different ways.

2. Course package

course/
├── manifest.yaml
├── chapters/
│   └── chapter-id/
│       ├── chapter.yaml
│       └── lessons/
│           └── lesson.mcf
└── assets/

manifest.yaml, chapters/, and at least one declared lesson are required. assets/ is optional. Ordering comes from YAML declarations, never filenames.

3. Root manifest

mcf: "1.0"
id: intro-physics
title: "Introduction to Physics"
language: en
description: "A first course in physics."
authors:
  - "Example Author"
license: CC-BY-4.0
version: "1.0.0"
cover: assets/images/cover.svg
chapters:
  - source: chapters/motion

Required fields: mcf, id, title, language, chapters.

Optional fields: description, authors, license, version, cover.

Chapter source paths are relative to the course root and MUST identify directories under chapters/.

4. Chapter package

id: motion
title: "Motion"
description: "Distance, velocity, and acceleration."
lessons:
  - lessons/01-introduction.mcf
  - lessons/02-velocity.mcf

Required fields: id, title, lessons. description is optional. Lesson paths are relative to the chapter directory.

5. Lessons

A .mcf file is Markdown with YAML frontmatter followed by one or more activities.

---
id: velocity
title: "Velocity"
---

:::mcf-activity
type: notes
id: velocity-notes
title: "Understanding velocity"
:::

Velocity is displacement over time.

:::mcf-end

Required frontmatter fields: id, title. Optional fields: description, authors, license.

Content outside activity containers is invalid except blank lines and comments.

6. Activities

An activity begins with :::mcf-activity, contains YAML metadata, closes its header with :::, and ends with :::mcf-end.

Required fields: type, id. title is optional.

MCF 1.0 activity types:

  • notes: instructional content;
  • practice: formative work;
  • assessment: evaluative work.

Assessment activities MAY define passing_score from 0 through 1. Practice and assessment activities MAY define randomize and positive-integer question_pool_size.

Activity type describes educational purpose. It does not prescribe UI, attempts, feedback timing, or storage.

7. Rich content

Rich content uses CommonMark-compatible Markdown. Readers MUST support paragraphs, headings, emphasis, lists, links, block quotes, fenced code, and images. Readers SHOULD support tables.

Math uses $...$ inline and $$...$$ for display math.

Images use Markdown:

![Graph](../../../assets/images/graph.svg)

Audio and video use directives:

@[audio](../../../assets/audio/example.mp3 "Example")
@[video](../../../assets/video/example.mp4 "Example")
@[video](youtube:VIDEO_ID "Online video")

Media may appear anywhere rich content is allowed, including prompts, options, hints, and explanations.

8. Question block

MCF 1.0 defines one structured fenced block:

```mcf-question
id: q1
type: multiple_choice
prompt: "Which quantity includes direction?"
options:
  - id: speed
    text: "Speed"
  - id: velocity
    text: "Velocity"
answer: velocity
hint: "Think about vectors."
explanation: "Velocity includes magnitude and direction."
points: 1
required: true
```

Common required fields: id, type, prompt.

Common optional fields: hint, explanation, points (default 1), required (default true).

9. Question types

multiple_choice

Requires options and answer. answer is one option ID.

multiple_select

Requires options and answer. answer is a list of option IDs; order is insignificant.

true_false

Requires boolean answer.

numeric

Requires numeric answer. Optional non-negative tolerance is an absolute difference, default 0.

short_answer

Requires string answer. Basic automatic comparison trims surrounding whitespace and compares case-insensitively.

essay

Captures a written response and MUST NOT be treated as objectively correct by the source format.

Essay questions MAY define:

  • minimum_words: positive integer;
  • minimum_sentences: positive integer;
  • keywords: non-empty list of strings;
  • minimum_keywords: positive integer no greater than the keyword count.

These fields define response-completion requirements, not correctness. Word, sentence, and keyword counting MUST be deterministic and documented by readers that evaluate completion.

10. Identifiers

Identifiers MUST match:

[a-z][a-z0-9._-]*

Chapter and lesson IDs are unique within the course. Activity and question IDs are unique within the lesson. Option IDs are unique within the question. IDs SHOULD remain stable when titles change.

11. Paths

Paths use forward slashes and MUST NOT escape the course root. Manifest chapter sources are course-root-relative. Chapter lesson paths are chapter-directory-relative. Other local paths are resolved relative to the containing file unless explicitly stated otherwise.

A missing referenced local file makes a course invalid. Remote URLs are valid but may require network access.

12. Validation and conformance

A valid MCF 1.0 course has valid YAML, required structure and fields, resolvable paths, supported core types, valid identifiers, unique IDs, and valid type-specific question fields.

An MCF 1.0 reader MUST preserve declared ordering, understand all core fields and types, and report invalid source rather than silently guessing.

An MCF 1.0 writer MUST produce valid source and stable, non-conflicting IDs.

A compiler is one kind of reader. Its output is not standardized.

13. Versioning

The root manifest MUST declare mcf: "1.0". MCF 1.0 has no vendor-extension mechanism. New official activities, blocks, or question types may be standardized in later versions. Breaking changes require a new major version.

14. Out of scope

MCF 1.0 does not define generated HTML, CSS, JavaScript, player files, compiler modules, databases, local storage, progress records, authentication, analytics, certificates, badges, labs, simulations, interactive diagrams, coding sandboxes, microphone analysis, or music-specific interaction.