Skip to content

Commit 263369c

Browse files
JasonWarrenUKJasonWarrenUK
committed
docs: update ref doc
1 parent 4ef5707 commit 263369c

File tree

1 file changed

+390
-0
lines changed

1 file changed

+390
-0
lines changed

‎docs/dev/wip/course-xml-schema-and-validator.md‎

Lines changed: 390 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,390 @@
1+
# Module XML Schema, Validation, and Course Structure Analysis
2+
3+
## 1. MODULE XML STRUCTURE
4+
5+
The module XML schema is defined in /Users/jasonwarren/code/rhea/src/data/templates/metis/outputSchema.xml and has the following root-level
6+
structure:
7+
8+
```xml
9+
<Module>
10+
<Metadata> <!--OPTIONAL-->
11+
<GenerationInfo>
12+
<Timestamp/>
13+
<Source/>
14+
<Model/>
15+
<InputSources/>
16+
</GenerationInfo>
17+
<Changelog/>
18+
<ProvenanceTracking/>
19+
</Metadata>
20+
<ModuleOverview>
21+
<ModuleDescription/>
22+
<ModuleObjectives>
23+
<ModuleObjective> (min 3)
24+
<Name />
25+
<Details />
26+
</ModuleObjective>
27+
</ModuleObjectives>
28+
</ModuleOverview>
29+
<ResearchTopics>
30+
<PrimaryTopics>
31+
<PrimaryTopic> <!--min 5-->
32+
<TopicName/>
33+
<TopicDescription/>
34+
</PrimaryTopic>
35+
</PrimaryTopics>
36+
<StretchTopics> <!--OPTIONAL-->
37+
<StretchTopic/>
38+
</StretchTopics>
39+
</ResearchTopics>
40+
<Projects>
41+
<ProjectBriefs>
42+
<ProjectBrief> <!--min 2-->
43+
<Overview>
44+
<Name/>
45+
<Task/>
46+
<Focus/>
47+
</Overview>
48+
<Criteria/>
49+
<Skills>
50+
<Skill> <!--min 3-->
51+
<Name/>
52+
<Details/>
53+
</Skill>
54+
</Skills>
55+
<Examples>
56+
<Example> <!--min 3-->
57+
<Name/>
58+
<Description/>
59+
</Example>
60+
</Examples>
61+
</ProjectBrief>
62+
</ProjectBriefs>
63+
<ProjectTwists>
64+
<ProjectTwist> <!--min 2-->
65+
<Name/>
66+
<Task/>
67+
<ExampleUses>
68+
<Example/>
69+
</ExampleUses>
70+
</ProjectTwist>
71+
</ProjectTwists>
72+
</Projects>
73+
<AdditionalSkills>
74+
<SkillsCategory> <!--at least 1-->
75+
<Name/>
76+
<Skill> <!--at least 1 per category-->
77+
<SkillName/>
78+
<Importance/>
79+
<SkillDescription/>
80+
</Skill>
81+
</SkillsCategory>
82+
</AdditionalSkills>
83+
<Notes/> <!--OPTIONAL-->
84+
</Module>
85+
```
86+
87+
### Key Validation Requirements (from `moduleValidator.ts`):
88+
89+
- Root element must be <Module>
90+
- Min 3 learning objectives with name attribute and content
91+
- Min 5 primary research topics with name attribute
92+
- Optional stretch topics
93+
- Min 2 project briefs, each with:
94+
- Task, Focus, Criteria (required)
95+
- Min 3 skills per brief
96+
- Min 3 examples per brief
97+
- Min 2 project twists, each with:
98+
- Task (required)
99+
- Min 2 examples
100+
- Min 1 additional skills category, each with at least 1 skill
101+
102+
---
103+
104+
## 2. VALIDATION IMPLEMENTATION
105+
106+
File: /Users/jasonwarren/code/rhea/src/lib/schemas/moduleValidator.ts
107+
108+
The validator uses @xmldom/xmldom for both browser and Node.js compatibility and returns a ValidationResult interface:
109+
110+
```ts
111+
interface ValidationResult {
112+
valid: boolean;
113+
errors: string[]; // Blocking validation failures
114+
warnings: string[]; // Non-blocking issues (e.g., missing optional Metadata)
115+
}
116+
````
117+
118+
Validation Pattern:
119+
1. Parse XML string using DOMParser
120+
2. Check for XML parsing errors
121+
3. Validate root element is <Module>
122+
4. Validate each section recursively:
123+
- Description (required)
124+
- Learning Objectives (required, min 3)
125+
- Research Topics (required, min 5 primary)
126+
- Projects (required, min 2 briefs + min 2 twists)
127+
- Additional Skills (required, min 1 category)
128+
- Metadata (optional, but generates warnings if missing)
129+
130+
Key Pattern: Validators use getElementsByTagName() to find children and validate both attributes and text content. This allows flexibility in XML
131+
structure while enforcing cardinality constraints.
132+
133+
---
134+
135+
## 3. COURSE DATA STRUCTURE (Themis)
136+
137+
File: /Users/jasonwarren/code/rhea/src/lib/types/themis.ts
138+
139+
### CourseData (Top-level)
140+
141+
```ts
142+
interface CourseData {
143+
id: string; // UUID
144+
title: string;
145+
description: string;
146+
logistics: {
147+
totalWeeks: number;
148+
daysPerWeek: number;
149+
startDate?: string; // Optional
150+
};
151+
learners: {
152+
cohortSize: number;
153+
teamBased: boolean;
154+
teamSize?: number;
155+
prerequisites: string;
156+
experience: {
157+
prereq: '<= 1 year' | '1-3 years' | '>= 4 years';
158+
focus: 'no experience' | 'limited experience' | 'skilled amateur' | 'current professional';
159+
};
160+
};
161+
structure: 'facilitated' | 'peer-led'; // Key pedagogical choice
162+
arcs: Arc[]; // Thematic organizational layer
163+
courseNarrative?: string; // AI-generated overall narrative
164+
progressionNarrative?: string; // How arcs connect temporally
165+
createdAt: Date;
166+
updatedAt: Date;
167+
}
168+
````
169+
170+
### Arc (Thematic Container)
171+
172+
```ts
173+
interface Arc {
174+
id: string; // UUID
175+
order: number; // 1, 2, 3...
176+
titleInput: TitleInput; // Supports AI generation or literal
177+
title: string; // Current/finalized title
178+
description: string;
179+
themeInput: TitleInput; // Supports AI generation or literal
180+
theme: string; // Current/finalized theme
181+
durationWeeks: number;
182+
arcThemeNarrative?: string; // AI narrative explaining thematic focus
183+
arcProgressionNarrative?: string; // How modules within arc connect
184+
modules: ModuleSlot[]; // Modules within this arc
185+
}
186+
````
187+
188+
### ModuleSlot (Module Reference within Arc)
189+
190+
```ts
191+
interface ModuleSlot {
192+
id: string; // UUID
193+
arcId: string; // Reference to parent arc
194+
order: number; // Order within arc (1, 2, 3...)
195+
titleInput: TitleInput; // Supports AI generation
196+
title: string; // Current/finalized title
197+
description: string;
198+
themeInput?: TitleInput; // Optional theme
199+
theme?: string;
200+
durationWeeks: number;
201+
status: 'planned' | 'overview-ready' | 'generating' | 'complete' | 'error';
202+
lastAttemptedGeneration?: 'overview' | 'full'; // Retry tracking
203+
overview?: ModuleOverview; // Lightweight generation before full module
204+
learningObjectives?: string[]; // Deprecated - use overview
205+
keyTopics?: string[]; // Deprecated - use overview
206+
moduleData?: {
207+
xmlContent: string; // Full module specification (XML)
208+
generatedAt: Date;
209+
};
210+
inputFiles?: {
211+
projectsData?: any;
212+
skillsData?: any;
213+
researchData?: any;
214+
};
215+
errorMessage?: string;
216+
}
217+
````
218+
219+
### ModuleOverview (Lightweight Pre-generation)
220+
221+
```ts
222+
interface ModuleOverview {
223+
generatedTitle?: string; // AI-suggested title
224+
generatedTheme?: string; // AI-suggested theme
225+
learningObjectives: string[]; // What learners will gain
226+
prerequisites: string[]; // What learners need first
227+
keyConceptsIntroduced: string[]; // Main new topics
228+
generatedAt: Date;
229+
}
230+
````
231+
232+
### Key Relationships
233+
234+
- CourseData → many Arc[] (thematic organization)
235+
- Arc → many ModuleSlot[] (temporal sequence)
236+
- ModuleSlot.moduleData.xmlContent → Full module XML (from Metis)
237+
- Total course weeks = sum of arc weeks = sum of all module weeks
238+
239+
---
240+
241+
## 4. EXISTING EXPORT FUNCTIONALITY
242+
243+
Course XML Export
244+
245+
File: /Users/jasonwarren/code/rhea/src/lib/utils/validation/outputSerialiser.ts
246+
247+
### Current Course XML Schema (wraps CourseData structure):
248+
249+
```xml
250+
<Course name="..." doc_date="YYYY-MM-DD" doc_time="HHMM">
251+
<CourseProps arcs="N" modules="N" weeks="N" days="N">
252+
<CourseMetadata/>
253+
<CourseLogistics arcs="N" modules="N">
254+
<TotalArcs/>
255+
<TotalModules/>
256+
</CourseLogistics>
257+
<CourseTemporal weeks="N" days="N" start_date="..." end_date="...">
258+
<StartDate />
259+
<TotalWeeks />
260+
<DaysPerWeek />
261+
<TotalDays />
262+
<EndDate />
263+
</CourseTemporal>
264+
</CourseProps>
265+
<CohortProps learners="N" learners_type="assumed">
266+
<CohortAssumptions learners="N">
267+
<AssumedCohortSize/>
268+
<AssumedTeamSize/>
269+
</CohortAssumptions>
270+
</CohortProps>
271+
<CourseDescription paragraphs="N">
272+
<DescriptionParagraph order="1"/>
273+
</CourseDescription>
274+
<CourseContent arcs="N" modules="N">
275+
<CourseProgression paragraphs="N">
276+
<ProgressionParagraph/>
277+
</CourseProgression>
278+
<Arcs count="N">
279+
<Arc order="N" name="..." modules="N" weeks="N">
280+
<ArcDescription paragraphs="N">
281+
<DescriptionParagraph/>
282+
</ArcDescription>
283+
<ArcProps>
284+
<ArcMetadata />
285+
<ArcLogistics modules="N" />
286+
<ArcTemporal weeks="N" days="N">
287+
<StartDate />
288+
<EndDate />
289+
</ArcTemporal>
290+
</ArcProps>
291+
<ArcContent modules="N" themes="1">
292+
<Themes count="1">
293+
<ArcTheme name="..." order="1"/>
294+
</Themes>
295+
<ArcProgression>
296+
<ArcProgressionNarrative/>
297+
</ArcProgression>
298+
<Modules count="N">
299+
<Module in_arc="N" order="N" name="..." weeks="N" days="N">
300+
<ModuleDescription/>
301+
<ModuleProps>
302+
<ModuleMetadata />
303+
<ModuleTemporal>
304+
<StartDate />
305+
<TotalWeeks />
306+
<EndDate />
307+
</ModuleTemporal>
308+
</ModuleProps>
309+
<ModuleContent learning_objectives="N" key_topics="N" projects="0">
310+
<ModuleLearningObjectives count="N">
311+
<LearningObjective order="N"/>
312+
</ModuleLearningObjectives>
313+
<ModuleKeyTopics count="N">
314+
<KeyTopic order="N"/>
315+
</ModuleKeyTopics>
316+
<ModuleProjects count="0" />
317+
</ModuleContent>
318+
</Module>
319+
</Modules>
320+
</ArcContent>
321+
</Arc>
322+
</Arcs>
323+
</CourseContent>
324+
</Course>
325+
```
326+
327+
Export Functions:
328+
- serialiseCourseToXml(course: CourseData): string - Convert to XML
329+
- generateXmlFilename(course: CourseData): string - Date-based filename
330+
- downloadCourseXml(course: CourseData): void - Browser download trigger
331+
332+
### Theia Content Exporter
333+
334+
File: /Users/jasonwarren/code/rhea/src/lib/services/theiaService.ts
335+
336+
Handles export in multiple formats (markdown, HTML, JSON) at various detail levels (minimal, summary, detailed, complete) for both courses and
337+
individual modules.
338+
339+
Export Pattern:
340+
1. Content mapping (XML/data → typescript structure)
341+
2. Format conversion (markdown/HTML/JSON)
342+
3. Filename generation (date-prefix + sanitized title)
343+
4. Browser download via Blob
344+
345+
---
346+
347+
## 5. KEY INSIGHTS FOR COURSE XML SCHEMA DESIGN
348+
349+
### Current Gaps I've Identified:
350+
351+
1. Module Content Not Embedded: Current course XML only contains lightweight module metadata (title, description, objectives, topics). The full
352+
module XML (with projects, twists, additional skills) is stored separately in ModuleSlot.moduleData.xmlContent.
353+
2. No Module References in Course XML: The existing outputSerialiser.ts creates a course-level overview XML but doesn't embed or reference the full
354+
module specifications.
355+
3. Thematic Structure Preserved: The Arc → ModuleSlot hierarchy is already well-modeled, so course XML should preserve this hierarchical structure.
356+
357+
### Design Recommendations:
358+
359+
For a course-level XML schema that wraps complete modules:
360+
361+
1. Decide on embedding strategy:
362+
- Shallow: Reference module XML files (xref/link approach)
363+
- Deep: Embed full module XML as child elements
364+
- Hybrid: Include module overview + xref to full spec
365+
2. Preserve hierarchy:
366+
- Maintain Arc → Module nesting
367+
- Include arc thematic narratives
368+
- Include progression narratives
369+
3. Follow existing patterns:
370+
- Use attributes for metadata and counts (doc_date, order, name, weeks)
371+
- Use child elements for content (descriptions, narratives, objectives)
372+
- Use plural tags for collections (Arcs, Modules, LearningObjectives)
373+
- Use count attributes for cardinality validation
374+
4. Validation structure: Create a courseValidator.ts pattern that validates:
375+
- Course-level requirements (title, logistics, learners, structure)
376+
- Arc requirements (order, title, theme, duration)
377+
- Module requirements (order, title, duration, status)
378+
- Temporal consistency (module weeks ≤ arc weeks ≤ course weeks)
379+
380+
---
381+
382+
## 6. File Paths Reference:
383+
384+
- Module Schema: /Users/jasonwarren/code/rhea/src/data/templates/metis/outputSchema.xml
385+
- Module Validator: /Users/jasonwarren/code/rhea/src/lib/schemas/moduleValidator.ts
386+
- Themis Types: /Users/jasonwarren/code/rhea/src/lib/types/themis.ts
387+
- Themis Stores: /Users/jasonwarren/code/rhea/src/lib/stores/themisStores.ts
388+
- Course XML Export: /Users/jasonwarren/code/rhea/src/lib/utils/validation/outputSerialiser.ts
389+
- Course Validation: /Users/jasonwarren/code/rhea/src/lib/utils/theia/courseValidator.ts
390+
- Export Service: /Users/jasonwarren/code/rhea/src/lib/services/theiaService.ts

0 commit comments

Comments
 (0)