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:
47 files changed
+10568
-55
No files matched your search
@@ -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(§ion)
|
||||
}
|
||||
Role::Glossary => Section::GLOSSARY.contains(§ion),
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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,
|
||||
})
|
||||
}
|
||||
|
||||
Reference in new issue
Block a user