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

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, 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) 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:

• 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	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	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	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 with comprehensive examples in 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. 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, preventing runtime errors from schema mismatches during course rendering or editing operations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}