feat(schema): 2.1 types, fragments, and JSON Schemas

Add the term, equation, value, and misconception registries
(src/model/course/glossary.rs) and the new optional fields on objectives,
targets, lectures, readings, bank options, and policy. Load registry
entries from objective files, glossary.yaml, and course.yaml, with one
definition site per id as for every other registry. Port every edit in
docs/design/2.1/build_schemas.py into the hand-written schema builders,
add glossary.schema.json, and test the generated schemas against the
targets; the only differences are two 2.0 spellings the code already had.

The 2.0 example fragments load and validate unchanged. The 2.1 example
bank gains `status: draft`, which every coursebank item requires.
tests/docs.rs skips docs/design/, which holds design records rather than
guide pages.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
alexmandClaude committed 2026-11-16 11:55:18 -05:00
1 parent 15175f64fd
commit 51a2fd235f
47 files changed
+10568 -55

No files matched your search

+133 -6
View File
@@ -12,7 +12,10 @@
//! course.yaml course, policy, units
//! references.yaml references
//! lectures/l-1-2.yaml one lecture, its readings, and what it teaches
//! objectives/lo-x.yaml one objective and its targets
//! objectives/lo-x.yaml one objective, its targets, and the glossary entries
//! its targets are the first to need
//! glossary.yaml terms, equations, values, and misconceptions that
//! belong to no single objective
//! ```
//!
//! The merge happens in memory on every command. Nothing is generated on disk
@@ -58,6 +61,7 @@ use std::path::{Path, PathBuf};
use serde::{Deserialize, Serialize};
use super::glossary::{Equation, Misconception, Term, Value};
use super::{
COURSE_FILE, Course, CourseFile, Lecture, Objective, Policy, Reference, SCHEMA_VERSION,
SUPPORTED_MAJORS, Stimulus, Target, Unit,
@@ -69,6 +73,11 @@ use crate::yaml;
/// The file holding the bibliography when it is kept out of `course.yaml`.
pub const REFERENCES_FILE: &str = "references.yaml";
/// The file holding glossary entries that belong to no single objective: the
/// cross-cutting ones, and everything `coursebank migrate glossary` brings in
/// until each entry is moved to the objective file whose targets first need it.
pub const GLOSSARY_FILE: &str = "glossary.yaml";
/// One registry section of a course.
///
/// Used to say which file a fact came from, and to keep a fragment from
@@ -91,11 +100,19 @@ pub enum Section {
References,
/// Shared stimuli.
Stimuli,
/// Terms.
Terms,
/// Equations.
Equations,
/// Taught values.
Values,
/// Named misconceptions.
Misconceptions,
}
impl Section {
/// Every section, in the order a merged course lists them.
pub const ALL: [Section; 8] = [
pub const ALL: [Section; 12] = [
Section::Course,
Section::Policy,
Section::Units,
@@ -104,6 +121,19 @@ impl Section {
Section::Targets,
Section::References,
Section::Stimuli,
Section::Terms,
Section::Equations,
Section::Values,
Section::Misconceptions,
];
/// The four registries 2.1 adds, which any objective file, `glossary.yaml`,
/// or `course.yaml` may define.
pub const GLOSSARY: [Section; 4] = [
Section::Terms,
Section::Equations,
Section::Values,
Section::Misconceptions,
];
/// The YAML key this section is written under.
@@ -117,6 +147,10 @@ impl Section {
Section::Targets => "learning_targets",
Section::References => "references",
Section::Stimuli => "stimuli",
Section::Terms => "terms",
Section::Equations => "equations",
Section::Values => "values",
Section::Misconceptions => "misconceptions",
}
}
@@ -131,6 +165,10 @@ impl Section {
Section::Targets => "target",
Section::References => "reference",
Section::Stimuli => "stimulus",
Section::Terms => "term",
Section::Equations => "equation",
Section::Values => "value",
Section::Misconceptions => "misconception",
}
}
@@ -141,6 +179,9 @@ impl Section {
Section::Lectures => "lectures/*.yaml",
Section::Objectives | Section::Targets | Section::Stimuli => "objectives/*.yaml",
Section::References => REFERENCES_FILE,
Section::Terms | Section::Equations | Section::Values | Section::Misconceptions => {
"objectives/*.yaml or glossary.yaml"
}
}
}
}
@@ -162,6 +203,8 @@ pub enum Role {
Lecture,
/// A file under `objectives/`.
Objective,
/// `glossary.yaml`.
Glossary,
}
impl Role {
@@ -171,10 +214,13 @@ impl Role {
Role::Root => true,
Role::References => section == Section::References,
Role::Lecture => section == Section::Lectures,
Role::Objective => matches!(
section,
Section::Objectives | Section::Targets | Section::Stimuli
),
Role::Objective => {
matches!(
section,
Section::Objectives | Section::Targets | Section::Stimuli
) || Section::GLOSSARY.contains(&section)
}
Role::Glossary => Section::GLOSSARY.contains(&section),
}
}
@@ -185,6 +231,7 @@ impl Role {
Role::References => "references",
Role::Lecture => "lecture",
Role::Objective => "objective",
Role::Glossary => "glossary",
}
}
}
@@ -237,6 +284,22 @@ pub struct Fragment {
/// Shared stimuli by id.
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub stimuli: BTreeMap<String, Stimulus>,
/// Terms by id.
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub terms: BTreeMap<String, Term>,
/// Equations by id.
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub equations: BTreeMap<String, Equation>,
/// Taught values by id.
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub values: BTreeMap<String, Value>,
/// Named misconceptions by id.
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub misconceptions: BTreeMap<String, Misconception>,
}
impl Fragment {
@@ -286,6 +349,18 @@ impl Fragment {
if !self.stimuli.is_empty() {
out.push(Section::Stimuli);
}
if !self.terms.is_empty() {
out.push(Section::Terms);
}
if !self.equations.is_empty() {
out.push(Section::Equations);
}
if !self.values.is_empty() {
out.push(Section::Values);
}
if !self.misconceptions.is_empty() {
out.push(Section::Misconceptions);
}
out
}
}
@@ -315,6 +390,10 @@ pub fn files(layout: &Layout) -> Result<Vec<(PathBuf, Role)>> {
if references.is_file() {
out.push((references, Role::References));
}
let glossary = layout.glossary_file();
if glossary.is_file() {
out.push((glossary, Role::Glossary));
}
for path in yaml::list_yaml(&layout.lectures())? {
out.push((path, Role::Lecture));
}
@@ -371,6 +450,10 @@ struct Merge {
targets: BTreeMap<String, Target>,
references: BTreeMap<String, Reference>,
stimuli: BTreeMap<String, Stimulus>,
terms: BTreeMap<String, Term>,
equations: BTreeMap<String, Equation>,
values: BTreeMap<String, Value>,
misconceptions: BTreeMap<String, Misconception>,
origins: BTreeMap<(Section, String), PathBuf>,
issues: Vec<String>,
}
@@ -492,6 +575,46 @@ impl Merge {
&mut self.issues,
);
}
if role.allows(Section::Terms) {
absorb(
&mut self.terms,
fragment.terms,
Section::Terms,
path,
&mut self.origins,
&mut self.issues,
);
}
if role.allows(Section::Equations) {
absorb(
&mut self.equations,
fragment.equations,
Section::Equations,
path,
&mut self.origins,
&mut self.issues,
);
}
if role.allows(Section::Values) {
absorb(
&mut self.values,
fragment.values,
Section::Values,
path,
&mut self.origins,
&mut self.issues,
);
}
if role.allows(Section::Misconceptions) {
absorb(
&mut self.misconceptions,
fragment.misconceptions,
Section::Misconceptions,
path,
&mut self.origins,
&mut self.issues,
);
}
}
/// Records a section that may only be declared once.
@@ -606,6 +729,10 @@ impl Merge {
learning_targets: self.targets,
references: self.references,
stimuli: self.stimuli,
terms: self.terms,
equations: self.equations,
values: self.values,
misconceptions: self.misconceptions,
origins: self.origins,
})
}