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

+650
View File
@@ -0,0 +1,650 @@
// SPDX-License-Identifier: Prosperity-3.0.0
// Copyright Scienting
// Source: https://git.scient.ing/education/coursebank
//! The four registries 2.1 adds: terms, equations, values, and misconceptions.
//!
//! A lecture was specified by its objectives, its targets, and its readings.
//! Everything else it provides lived in files coursebank could not see: the
//! course's vocabulary in `terms.yaml`, its numbers in `values.yaml`, its named
//! mistakes in each pipeline's notes, and its equations nowhere at all. The
//! lecture page showed students half of what they study from, and the slide,
//! brief, and item pipelines each kept a copy of the rest that drifted.
//!
//! These registries are keyed by id like [`CourseFile::learning_targets`], and
//! they follow the same rule: an id has one definition site. Each id carries a
//! prefix, `term-`, `eq-`, `val-`, or `mis-`, so an id in an item, a reading, a
//! report, or a brace reference says which registry it belongs to without a
//! lookup.
//!
//! The direction of every edge matters. A [`Target`] lists the entries it needs,
//! and nothing points back: which lecture introduces a term is derived from the
//! first target, in teaching order, that lists it, the same way an objective's
//! lectures are derived from `teaches`. There is no `introduced_in` field to
//! keep in step.
//!
//! Each prose field is either student-facing or instructor-facing, and the
//! difference is enforced by what the renderers read. `notes_private`,
//! `evidence`, `conflicts`, `status`, and a target's [`Authoring`] notes never
//! reach a student page or a student-visible export.
//!
//! [`CourseFile::learning_targets`]: super::CourseFile::learning_targets
//! [`Target`]: super::Target
use serde::{Deserialize, Serialize};
use crate::taxonomy::ErrorType;
/// The id prefix of a term.
pub const TERM_PREFIX: &str = "term-";
/// The id prefix of an equation.
pub const EQUATION_PREFIX: &str = "eq-";
/// The id prefix of a value.
pub const VALUE_PREFIX: &str = "val-";
/// The id prefix of a misconception.
pub const MISCONCEPTION_PREFIX: &str = "mis-";
/// Whether an entry is waiting for the instructor.
///
/// A pipeline that adds an entry marks it proposed, and the instructor approves
/// it by deleting the line. Checks treat proposed entries exactly like approved
/// ones, so a new entry is checked from the day it is written; the linter only
/// counts how many are waiting. This is the `terms.yaml` convention, kept.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum EntryStatus {
/// Added by a pipeline or a collaborator, not yet approved.
Proposed,
/// Approved. The same as leaving the field out.
Approved,
}
/// A citation into `references`, with a location inside the work.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SourceRef {
/// Citation key into [`super::CourseFile::references`].
#[serde(rename = "ref")]
pub reference: String,
/// Where inside the work: `§6.1`, `pp. 4-9`, `eq. 3.12`.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub locator: Option<String>,
}
/// Whether a student can look a term up under the name the course uses.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum TermKind {
/// The textbooks use this name for this idea.
#[default]
Standard,
/// A standard idea under the course's own name or notation. A student can
/// look it up only if told the textbook name.
Renamed,
/// A label or metaphor the course invented. No textbook uses it.
Coined,
}
impl TermKind {
/// Whether this is the default, so serializing can leave it out.
fn is_standard(&self) -> bool {
*self == TermKind::Standard
}
/// The YAML spelling.
pub fn as_str(self) -> &'static str {
match self {
TermKind::Standard => "standard",
TermKind::Renamed => "renamed",
TermKind::Coined => "coined",
}
}
}
/// A name an assigned text uses for a term.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct TextbookName {
/// The name the text uses.
pub term: String,
/// Citation key into `references`; absent for a plain-English equivalent.
#[serde(rename = "ref", default, skip_serializing_if = "Option::is_none")]
pub reference: Option<String>,
/// Where that text uses it.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub locator: Option<String>,
}
/// One term students meet in this course.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Term {
/// The word or phrase as this course writes it. Student-facing.
pub term: String,
/// One plain sentence that defines the term without using it.
/// Student-facing; may hold brace references.
pub definition: String,
/// Whether a student can look it up under this name.
#[serde(default, skip_serializing_if = "TermKind::is_standard")]
pub kind: TermKind,
/// What the assigned texts call it, the first-listed text first.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub textbook: Vec<TextbookName>,
/// Other surface forms that count as a use of the term: plurals,
/// abbreviations. Matching is case-insensitive and whole-word.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub variants: Vec<String>,
/// The notation, when the term names a quantity, in coursebank markup.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub symbol: Option<String>,
/// Units of the quantity the term names.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub units: Option<String>,
/// Coined terms only: the plain wording items write instead of the label.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub exam_wording: Option<String>,
/// Whether the entry is waiting for approval. Instructor-facing.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub status: Option<EntryStatus>,
/// Free-form tags.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub tags: Vec<String>,
/// Instructor-facing notes. Never rendered for students.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub notes_private: Option<String>,
}
impl Term {
/// The term and every variant: the surface forms that count as a use.
///
/// # Returns
///
/// Non-empty forms, the term first.
pub fn forms(&self) -> Vec<&str> {
std::iter::once(self.term.as_str())
.chain(self.variants.iter().map(String::as_str))
.filter(|w| !w.trim().is_empty())
.collect()
}
}
/// The six things a question can ask about a relation without evaluating it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum RelationForm {
/// Which way the output moves when one input rises.
Direction,
/// What the relation gives at a boundary.
Limit,
/// Whether a stated difference is large or negligible on the relation's
/// own scale.
Scale,
/// Which term governs an observation.
DominantTerm,
/// The reference state or normalizer.
HeldFixed,
/// A result the relation cannot support.
Misuse,
}
impl RelationForm {
/// Every form, in the order the objectives prompt lists them.
pub const ALL: [RelationForm; 6] = [
RelationForm::Direction,
RelationForm::Limit,
RelationForm::Scale,
RelationForm::DominantTerm,
RelationForm::HeldFixed,
RelationForm::Misuse,
];
/// The YAML spelling.
pub fn as_str(self) -> &'static str {
match self {
RelationForm::Direction => "direction",
RelationForm::Limit => "limit",
RelationForm::Scale => "scale",
RelationForm::DominantTerm => "dominant_term",
RelationForm::HeldFixed => "held_fixed",
RelationForm::Misuse => "misuse",
}
}
/// The form as a student reads it on a lecture page.
pub fn label(self) -> &'static str {
match self {
RelationForm::Direction => "direction",
RelationForm::Limit => "limit",
RelationForm::Scale => "scale",
RelationForm::DominantTerm => "dominant term",
RelationForm::HeldFixed => "held fixed",
RelationForm::Misuse => "misuse",
}
}
}
/// One symbol in an equation.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Symbol {
/// The symbol as it appears in `tex`.
pub symbol: String,
/// Term id, when the quantity has a glossary entry.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub term: Option<String>,
/// What the symbol stands for, when it has no term.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub meaning: Option<String>,
/// Units, when the symbol has no term or the term gives none.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub units: Option<String>,
}
/// Something a relation says that a question can test without evaluating it.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Implication {
/// Which of the six forms it takes.
pub form: RelationForm,
/// The implication as one student-facing sentence; may hold brace
/// references.
pub statement: String,
}
/// One relation students meet in this course.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Equation {
/// The name students would use. Student-facing.
pub name: String,
/// The relation in LaTeX, without surrounding dollar signs.
pub tex: String,
/// What the relation claims, in words. Student-facing; may hold brace
/// references.
pub says: String,
/// Every symbol in `tex`, in order of first appearance.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub symbols: Vec<Symbol>,
/// What the relation says that a question can test without evaluating it.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub implications: Vec<Implication>,
/// Conditions that must hold for the relation to apply. Student-facing.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub assumes: Vec<String>,
/// Cases where the relation breaks or misleads. Student-facing.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub fails_when: Vec<String>,
/// Students are expected to know it from memory.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub recall: Option<bool>,
/// Where the course's own source states it.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub source: Option<SourceRef>,
/// Whether the entry is waiting for approval. Instructor-facing.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub status: Option<EntryStatus>,
/// Free-form tags.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub tags: Vec<String>,
/// Instructor-facing notes. Never rendered for students.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub notes_private: Option<String>,
}
/// One number students are taught.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Value {
/// The quantity, specifically.
pub name: String,
/// The value as taught, rounded as students learn it.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub value: Option<f64>,
/// Low and high, when the course teaches a range rather than one value.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub range: Option<[f64; 2]>,
/// Units, as printed.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub units: Option<String>,
/// The one wording every material uses. `{val-...}` in prose renders this.
pub say: String,
/// The unrounded value, for explanations and solutions.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub exact: Option<f64>,
/// Term id of the quantity, when it has a glossary entry.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub term: Option<String>,
/// Where the number comes from.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub source: Option<SourceRef>,
/// Regular expressions for variants that must not appear in student-facing
/// text or items. Instructor-facing.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub conflicts: Vec<String>,
/// Students are expected to know it, so no item may print it.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub recall: Option<bool>,
/// Whether the entry is waiting for approval. Instructor-facing.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub status: Option<EntryStatus>,
/// Free-form tags.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub tags: Vec<String>,
/// Instructor-facing notes. Never rendered for students.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub notes_private: Option<String>,
}
/// Where a misconception has been seen.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum EvidenceKind {
/// An exam item drew it.
Exam,
/// A homework item drew it.
Homework,
/// An in-class poll drew it.
Poll,
/// The instructor has seen it.
Instructor,
/// The education literature reports it.
Literature,
/// An assigned text states or implies it, so the correction must name the
/// framing it replaces rather than contradict the text silently.
Textbook,
/// A simulated student, the weakest evidence.
Persona,
}
/// One sighting of a misconception. Instructor-facing.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Evidence {
/// Where it was seen.
pub kind: EvidenceKind,
/// What was seen: `Exam 2 Q23, 22% chose it.`
#[serde(default, skip_serializing_if = "Option::is_none")]
pub detail: Option<String>,
/// Citation key, for literature or textbook evidence.
#[serde(rename = "ref", default, skip_serializing_if = "Option::is_none")]
pub reference: Option<String>,
/// Where in that work.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub locator: Option<String>,
}
/// One named mistake.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Misconception {
/// The wrong idea as a student holds it. Student-facing.
pub belief: String,
/// Why it fails and what is true instead. Student-facing.
pub correction: String,
/// What kind of mistake it is, in the bank's terms.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub error_type: Option<ErrorType>,
/// Where it has been seen, strongest first. Instructor-facing.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub evidence: Vec<Evidence>,
/// Whether the entry is waiting for approval. Instructor-facing.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub status: Option<EntryStatus>,
/// Free-form tags.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub tags: Vec<String>,
/// Instructor-facing notes. Never rendered for students.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub notes_private: Option<String>,
}
/// Notes for whoever writes items, slides, or the brief from a target.
///
/// These are the per-target judgments the objectives prompt asks for and then
/// loses in chat output. Instructor-facing: never rendered for students.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Authoring {
/// The most demanding fair item at the ceiling: the evidence for it.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub ceiling_item: Option<String>,
/// What an item on this target hands the student.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub supplied: Vec<String>,
/// Conditions an item's stem must meet to stay fair.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub constraints: Vec<String>,
/// The arithmetic an item needs, and roughly how long it takes.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub number_work: Option<String>,
/// When the target tests a relation without evaluating it, which form.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub relation_form: Option<RelationForm>,
/// Named cases that teach this target, kept out of the target text.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub examples: Vec<String>,
}
/// What a lecture material link points at.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum MaterialKind {
/// The slide deck.
Slides,
/// The lecture brief.
Brief,
/// Notes.
Notes,
/// A notebook.
Notebook,
/// A recording.
Recording,
/// A homework set.
Homework,
/// Anything else.
Other,
}
impl MaterialKind {
/// The YAML spelling, which is also the default link text.
pub fn as_str(self) -> &'static str {
match self {
MaterialKind::Slides => "slides",
MaterialKind::Brief => "brief",
MaterialKind::Notes => "notes",
MaterialKind::Notebook => "notebook",
MaterialKind::Recording => "recording",
MaterialKind::Homework => "homework",
MaterialKind::Other => "other",
}
}
}
/// A link a lecture page lists beside the readings.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Material {
/// What it is.
pub kind: MaterialKind,
/// Link text. Defaults to the kind.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub title: Option<String>,
/// Where it lives.
pub url: String,
}
impl Material {
/// The link text: the title, else the kind.
pub fn label(&self) -> &str {
self.title.as_deref().unwrap_or(self.kind.as_str())
}
}
/// Which registry an id belongs to, read from its prefix.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum RefKind {
/// `term-...`
Term,
/// `eq-...`
Equation,
/// `val-...`
Value,
/// `mis-...`
Misconception,
/// `lo-...`
Objective,
/// `t-...`
Target,
}
impl RefKind {
/// The registry an id names by its prefix.
///
/// `term-` is tested before `t-`, since every term id also starts with `t`.
///
/// # Arguments
///
/// * `id` - the id.
///
/// # Returns
///
/// The kind, or `None` for an id with no registry prefix.
pub fn of(id: &str) -> Option<RefKind> {
[
(TERM_PREFIX, RefKind::Term),
(EQUATION_PREFIX, RefKind::Equation),
(VALUE_PREFIX, RefKind::Value),
(MISCONCEPTION_PREFIX, RefKind::Misconception),
("lo-", RefKind::Objective),
("t-", RefKind::Target),
]
.into_iter()
.find(|(prefix, _)| id.starts_with(prefix))
.map(|(_, kind)| kind)
}
/// What one entry is called in a message.
pub fn noun(self) -> &'static str {
match self {
RefKind::Term => "term",
RefKind::Equation => "equation",
RefKind::Value => "value",
RefKind::Misconception => "misconception",
RefKind::Objective => "objective",
RefKind::Target => "target",
}
}
}
/// Whether an id is a prefix followed by lowercase words joined by single
/// hyphens: the `^prefix-[a-z0-9]+(-[a-z0-9]+)*$` pattern the schemas state.
///
/// # Arguments
///
/// * `id` - the id to test.
/// * `prefix` - the prefix it must carry, hyphen included.
///
/// # Returns
///
/// `true` when the id matches.
pub fn is_prefixed_id(id: &str, prefix: &str) -> bool {
id.strip_prefix(prefix).is_some_and(|rest| {
!rest.is_empty()
&& !rest.starts_with('-')
&& !rest.ends_with('-')
&& !rest.contains("--")
&& rest
.chars()
.all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-')
})
}
/// Every brace reference in a piece of prose: `{term-...}`, `{eq-...}`,
/// `{val-...}`, `{mis-...}`, `{lo-...}`, or `{t-...}`.
///
/// Only a brace whose content is a prefixed id counts, so `10^{59}` and
/// `\text{final}` are never references. That is the same pattern the prototype
/// states as `\{((?:lo|t|term|eq|val|mis)-[a-z0-9]+(?:-[a-z0-9]+)*)\}`.
///
/// # Arguments
///
/// * `prose` - the text to scan.
///
/// # Returns
///
/// The ids in order of appearance, with the byte span of each brace pair.
pub fn brace_refs(prose: &str) -> Vec<(std::ops::Range<usize>, &str)> {
let mut out = Vec::new();
let mut from = 0;
while let Some(open) = prose[from..].find('{').map(|i| i + from) {
let Some(close) = prose[open..].find('}').map(|i| i + open) else {
break;
};
let inner = &prose[open + 1..close];
// A second `{` before the close means this opener was not a reference;
// resume at the inner one.
if let Some(nested) = inner.rfind('{') {
from = open + 1 + nested;
continue;
}
let referenced = RefKind::of(inner).is_some_and(|kind| {
let prefix = match kind {
RefKind::Term => TERM_PREFIX,
RefKind::Equation => EQUATION_PREFIX,
RefKind::Value => VALUE_PREFIX,
RefKind::Misconception => MISCONCEPTION_PREFIX,
RefKind::Objective => "lo-",
RefKind::Target => "t-",
};
is_prefixed_id(inner, prefix)
});
if referenced {
out.push((open..close + 1, inner));
}
from = close + 1;
}
out
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn a_term_id_is_not_read_as_a_target_id() {
assert_eq!(RefKind::of("term-gap"), Some(RefKind::Term));
assert_eq!(RefKind::of("t-gap"), Some(RefKind::Target));
assert_eq!(RefKind::of("lo-x"), Some(RefKind::Objective));
assert_eq!(RefKind::of("gap"), None);
}
#[test]
fn prefixed_ids_follow_the_schema_pattern() {
assert!(is_prefixed_id("term-gap-penalty", TERM_PREFIX));
assert!(is_prefixed_id("val-alignment-count-100", VALUE_PREFIX));
assert!(!is_prefixed_id("term-", TERM_PREFIX));
assert!(!is_prefixed_id("term-Gap", TERM_PREFIX));
assert!(!is_prefixed_id("term--gap", TERM_PREFIX));
assert!(!is_prefixed_id("gap", TERM_PREFIX));
}
#[test]
fn only_prefixed_ids_in_braces_are_references() {
let prose = "About 10^{59}, see {term-gap} and {eq-global-recurrence}; \
$U_\\text{final}$ and {t-align-fill-matrix}.";
let ids: Vec<&str> = brace_refs(prose).into_iter().map(|(_, id)| id).collect();
assert_eq!(
ids,
vec!["term-gap", "eq-global-recurrence", "t-align-fill-matrix"]
);
}
#[test]
fn a_reference_inside_latex_braces_is_still_found() {
let ids: Vec<&str> = brace_refs("\\frac{a}{b} {val-x}")
.into_iter()
.map(|(_, id)| id)
.collect();
assert_eq!(ids, vec!["val-x"]);
}
}