# How the Course DSL in OpenMAIC Defines Lesson Data Structure: A Complete Technical Guide

> Discover how the Course DSL in OpenMAIC defines lesson data structure with typed CourseDocument, stages, outlines, scenes, and version-aware validation. A complete technical guide.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: deep-dive
- Published: 2026-09-04

---

**The Course DSL in OpenMAIC structures lesson data as a strictly typed `CourseDocument` composed of three hierarchical sections—`stage` (metadata), `outline` (navigation index), and `scenes` (content array)—where each scene adheres to one of four typed schemas (`slide`, `quiz`, `interactive`, or `pbl`) enforced at runtime by version-aware validation logic.**

The OpenMAIC platform implements a domain-specific language (DSL) to standardize how AI agents and runtime systems parse, edit, and render educational content. The Course DSL ensures that every lesson stored in the system follows a predictable, type-safe JSON structure, enabling reliable interoperability between content creation tools and agent runtimes.

## The Three-Section CourseDocument Architecture

The root of the Course DSL is the **`CourseDocument`** type, a JSON document that partitions lesson data into three distinct top-level objects.

### Stage: Global Course Metadata

The **`stage`** section contains immutable administrative metadata for the entire course. According to the test fixtures in [`tests/agent-runtime/dsl-tools.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/agent-runtime/dsl-tools.test.ts), this object requires:

- `id`: Unique identifier for the course instance
- `name`: Human-readable course title
- `description`: Summary text for the curriculum
- `createdAt` / `updatedAt`: Unix timestamps for versioning

This section functions as the document header, providing context that remains constant regardless of content modifications within individual scenes.

### Outline: Hierarchical Lesson Navigation

The **`outline`** section serves as the table of contents, maintaining an ordered array of navigation items that map to scenes. Each entry in the `outlines` array contains:

- `id`: Correlation identifier linking to a specific scene
- `order`: Sequential position in the lesson flow
- `type`: Scene classification matching the corresponding scene object
- `title` / `description`: Display metadata for UI rendering
- `keyPoints`: Array of learning objectives or summary tags

This structure decouples navigation metadata from content payload, allowing agents to scan lesson structure without parsing heavy scene content.

### Scenes: Typed Content Containers

The **`scenes`** array contains the actual instructional content, with each element implementing the **`Scene`** discriminated union type. Every scene object declares a mandatory `type` field (`slide`, `quiz`, `interactive`, or `pbl`) and a `content` payload that varies by type.

## Scene Type Definitions and Content Schemas

The Course DSL defines four concrete scene implementations, each with a strict content schema validated at runtime.

### Slide Scenes with Canvas Elements

**Slide scenes** (`type: 'slide'`) implement a canvas-based content model suitable for traditional instructional presentations. As defined in the `slideScene` fixture, the `content` object contains a `canvas` property with an `elements` array supporting:

- `text` elements for instructional copy
- `image` assets for visual aids
- `audio` resources for narration

This schema mirrors presentation software structures, enabling drag-and-drop authoring tools to serialize canvas state directly into the DSL.

### Quiz Scenes with Assessment Data

**Quiz scenes** (`type: 'quiz'`) encapsulate assessment logic through a structured `questions` array. The schema (see `quizScene` in [`tests/agent-runtime/dsl-tools.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/agent-runtime/dsl-tools.test.ts)) requires each question object to specify:

- `id`: Unique question identifier
- `type`: Question format (e.g., multiple choice, true/false)
- `question`: Prompt text
- `options`: Array of possible answers
- `answer`: Correct option index/key
- `analysis`: Explanation text shown after submission

This structure supports immediate feedback systems and automated grading agents that parse answer keys without executing JavaScript.

### Interactive Scenes with Widget Configuration

**Interactive scenes** (`type: 'interactive'`) embed simulations and external widgets through two primary fields:

- `html`: String containing markup for the interactive component
- `widgetConfig`: Object describing simulation parameters, initialization data, and runtime configuration

The DSL treats these scenes as black-box containers where the `widgetConfig` schema varies by specific widget type, allowing extensibility while maintaining type safety through the `Scene` discriminated union.

### PBL Scenes with Project Structures

**Project-Based Learning (PBL) scenes** (`type: 'pbl'`) implement the most complex content schema through a `projectV2` object encapsulating:

- **Phases**: Major project stages with deadlines
- **Milestones**: Checkpoints within phases
- **Micro-tasks**: Granular deliverables assigned to learners
- **Roles**: Participant responsibilities and permissions

This schema supports collaborative learning workflows, enabling agents to decompose large projects into trackable sub-tasks while maintaining the hierarchical relationship between curriculum structure and student assignments.

## Validation and Versioning Strategy

The Course DSL enforces structural contracts through compile-time TypeScript definitions and runtime JSON schema validation.

### DSL Version Management

Every `CourseDocument` carries a top-level **`dslVersion`** field populated from the `DSL_VERSION` constant exported by `@openmaic/dsl`. This versioning strategy, defined in `packages/@openmaic/dsl/src/version.ts`, ensures that agent runtimes can handle schema migrations and deprecated field gracefully when parsing historical course data.

### Runtime Schema Enforcement

The agent runtime validates all course mutations against three distinct schemas defined in [`lib/server/agent-runtime/dsl-tools.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/dsl-tools.ts):

- **`PATCH_COURSE_SCHEMA`**: Validates partial updates and field modifications
- **`READ_COURSE_SCHEMA`**: Validates complete document retrieval responses
- **`GREP_COURSE_SCHEMA`**: Validates filtered queries returning document subsets

These schemas derive from **type-box** definitions, generating JSON Schema constraints that reject invalid scene types or malformed content payloads before persistence.

## Key Implementation Files

The Course DSL implementation spans multiple packages and modules within the OpenMAIC repository:

| File | Role |
|------|------|
| [`tests/agent-runtime/dsl-tools.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/agent-runtime/dsl-tools.test.ts) | Contains the `course()` fixture function and sample scene builders (`slideScene()`, `quizScene()`, `interactiveScene()`, `pblScene()`) that demonstrate valid DSL structure |
| [`lib/server/agent-runtime/dsl-tools.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/dsl-tools.ts) | Exports validation schemas (`PATCH_COURSE_SCHEMA`, `READ_COURSE_SCHEMA`) and type-box definitions that enforce DSL contracts at runtime |
| [`lib/server/agent-runtime/course-tools.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/course-tools.ts) | Defines the `CourseDocument` TypeScript interface and helper utilities for constructing agent toolsets that interact with course data |
| `packages/@openmaic/dsl/src/version.ts` | Exports `DSL_VERSION` constant and shared type definitions used across the runtime and client packages |

Together, these files constitute the complete Course DSL system that governs how OpenMAIC structures, validates, and versions lesson data throughout the platform lifecycle.

## Summary

- The **Course DSL** structures OpenMAIC lessons as `CourseDocument` objects with three mandatory sections: `stage` (metadata), `outline` (navigation), and `scenes` (content).
- **Four scene types** are supported—`slide`, `quiz`, `interactive`, and `pbl`—each with a distinct content schema optimized for specific pedagogical formats.
- **Validation** occurs through type-box generated schemas (`PATCH_COURSE_SCHEMA`, `READ_COURSE_SCHEMA`) that enforce type safety at runtime.
- **Versioning** is handled through the `DSL_VERSION` field from `@openmaic/dsl`, ensuring backward compatibility as schemas evolve.
- The complete reference implementation resides in [`lib/server/agent-runtime/dsl-tools.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/dsl-tools.ts) with comprehensive examples in [`tests/agent-runtime/dsl-tools.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/agent-runtime/dsl-tools.test.ts).

## Frequently Asked Questions

### What is the purpose of the `outline` section in a CourseDocument?

The `outline` section acts as a lightweight table of contents that maps navigation items to full scene objects. By separating navigation metadata (titles, descriptions, order) from heavy content payloads, agents can rapidly scan course structure and generate navigation UIs without parsing canvas elements or quiz questions stored in the `scenes` array.

### How does OpenMAIC validate course data against the DSL?

Runtime validation uses JSON Schema definitions generated from type-box types in [`lib/server/agent-runtime/dsl-tools.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/dsl-tools.ts). The system applies `PATCH_COURSE_SCHEMA` for updates, `READ_COURSE_SCHEMA` for retrievals, and `GREP_COURSE_SCHEMA` for queries, ensuring that every write operation respects the structural contracts defined for each scene type while maintaining the `dslVersion` compatibility.

### What scene types are supported in the Course DSL?

The DSL supports four typed scene variants: **slide** (canvas-based presentations), **quiz** (structured assessments with questions/answers), **interactive** (HTML/widgets with configuration objects), and **pbl** (project-based learning with phases, milestones, and micro-tasks). Each type implements a specific content schema while sharing common fields like `id`, `type`, and `order`.

### Where is the DSL version defined and enforced?

The version constant `DSL_VERSION` is exported from `@openmaic/dsl` (specifically `packages/@openmaic/dsl/src/version.ts`) and attached to every `CourseDocument` at the top level. Agent runtimes check this field before processing to ensure compatibility with the validation schemas in [`lib/server/agent-runtime/dsl-tools.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/dsl-tools.ts), preventing runtime errors from schema mismatches during course rendering or editing operations.