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

+681 -13
View File
@@ -20,8 +20,9 @@
use serde_json::{Value, json};
use crate::course::SCHEMA_VERSION;
use crate::course::glossary::RelationForm;
use crate::error::Result;
use crate::taxonomy::{CognitiveProcess, ErrorType, Flag, Level};
use crate::taxonomy::{CognitiveProcess, ErrorType, Flag, Format, Level};
/// The base URL schemas refer to each other by.
const BASE: &str = "https://coursebank.dev/schema";
@@ -37,6 +38,8 @@ pub enum Kind {
Lecture,
/// `objectives/*.yaml`.
Objective,
/// `glossary.yaml`.
Glossary,
/// `analysis/calibration.yaml`.
Calibration,
/// `analysis/administrations/*.yaml`.
@@ -49,11 +52,12 @@ pub enum Kind {
impl Kind {
/// Every kind.
pub const ALL: [Kind; 8] = [
pub const ALL: [Kind; 9] = [
Kind::Course,
Kind::References,
Kind::Lecture,
Kind::Objective,
Kind::Glossary,
Kind::Bank,
Kind::Assessment,
Kind::Calibration,
@@ -67,6 +71,7 @@ impl Kind {
Kind::References => "references.schema.json",
Kind::Lecture => "lecture.schema.json",
Kind::Objective => "objective.schema.json",
Kind::Glossary => "glossary.schema.json",
Kind::Calibration => "calibration.schema.json",
Kind::Measurements => "measurements.schema.json",
Kind::Bank => "bank.schema.json",
@@ -107,6 +112,7 @@ pub fn schema(kind: Kind) -> Value {
Kind::References => references_schema(),
Kind::Lecture => lecture_fragment_schema(),
Kind::Objective => objective_fragment_schema(),
Kind::Glossary => glossary_fragment_schema(),
Kind::Calibration => calibration_file_schema(),
Kind::Measurements => measurements_file_schema(),
Kind::Bank => bank_schema(),
@@ -218,6 +224,12 @@ fn cognitive_process() -> Value {
/// The distractor error-type enum, with each gloss in the description.
fn error_type() -> Value {
error_type_led("What kind of mistake this distractor is designed to catch.")
}
/// The error-type enum under a different opening sentence, so a registry
/// misconception and a distractor classify mistakes with the same list.
fn error_type_led(lead: &str) -> Value {
let all: Vec<&str> = ErrorType::ALL.iter().map(|e| e.as_str()).collect();
let glosses: Vec<String> = ErrorType::ALL
.iter()
@@ -226,10 +238,542 @@ fn error_type() -> Value {
json!({
"type": "string",
"enum": strings(&all),
"description": format!(
"What kind of mistake this distractor is designed to catch. {}",
glosses.join("; ")
)
"description": format!("{lead} {}", glosses.join("; "))
})
}
/// The sentence every student-facing prose field that accepts brace references
/// ends its description with.
const BRACES: &str = "May reference other entries in braces, {term-...}, {eq-...}, {val-...}, \
{mis-...}, {t-...} or {lo-...}; the validator checks each resolves and the \
renderer replaces it (a term with its linked name, an equation inline, a \
value with its `say`, a target with its number).";
/// A schema fragment for an optional string.
fn string(description: &str) -> Value {
json!({ "type": "string", "description": description })
}
/// A schema fragment for an optional string that may hold brace references.
fn prose(description: &str) -> Value {
string(&format!("{description} {BRACES}"))
}
/// A schema fragment for a required string that may hold brace references.
fn required_prose(description: &str) -> Value {
text(&format!("{description} {BRACES}"))
}
/// The relation forms, the six things a question can ask about an equation.
fn relation_forms() -> Value {
let all: Vec<&str> = RelationForm::ALL.iter().map(|f| f.as_str()).collect();
strings(&all)
}
/// An id-keyed registry whose ids carry a prefix.
fn id_map(prefix: &str, entry: Value, description: &str) -> Value {
json!({
"type": "object",
"description": description,
"propertyNames": { "pattern": format!("^{prefix}-[a-z0-9]+(-[a-z0-9]+)*$") },
"additionalProperties": entry
})
}
/// The `status` field every registry entry may carry.
fn entry_status() -> Value {
json!({
"type": "string",
"enum": ["proposed", "approved"],
"description": "proposed marks an entry a pipeline or a collaborator added for the \
instructor to approve; approve it by deleting the field or setting \
approved. Checks treat proposed entries like approved ones, so a new \
entry is checked from the day it is written. Absent means approved."
})
}
/// The instructor-only notes field.
fn notes_private() -> Value {
string(
"Instructor-facing. Never rendered on a student page or exported where a student can \
see it.",
)
}
/// A citation into `references` with a locator.
fn source_ref_schema() -> Value {
json!({
"type": "object",
"additionalProperties": false,
"required": ["ref"],
"description": "Where the course's own source states it.",
"properties": {
"ref": text("Citation key into `references`."),
"locator": string("Where inside the work: §6.1, pp. 4-9, eq. 3.12.")
}
})
}
/// One name an assigned text uses for a term.
fn textbook_name_schema() -> Value {
json!({
"type": "object",
"additionalProperties": false,
"required": ["term"],
"properties": {
"term": text("The name an assigned text uses."),
"ref": string("Citation key into `references`; omit for a plain-English equivalent."),
"locator": string("Where that text uses it.")
}
})
}
/// One term.
fn term_schema() -> Value {
json!({
"type": "object",
"additionalProperties": false,
"required": ["term", "definition"],
"description": "One term students meet in this course.",
"properties": {
"term": text(
"The word or phrase as this course writes it, as a student reads it on the \
lecture page."
),
"definition": required_prose(
"One plain sentence, student-facing, that defines the term without using it. \
Rendered in the lecture page's glossary and the course glossary."
),
"kind": {
"type": "string",
"enum": ["standard", "renamed", "coined"],
"description": "standard: the textbooks use this name for this idea (the \
default). renamed: a standard idea under the course's own name \
or notation; students can look it up only if told the textbook \
name. coined: a label or metaphor the course invented; no \
textbook uses it."
},
"textbook": {
"type": "array",
"items": textbook_name_schema(),
"description": "What the assigned texts call it, the first-listed text first. \
The linter flags a renamed or coined term without one, since a \
student needs a name a search will find."
},
"variants": string_array(
"Other surface forms that count as a use of the term: plurals, abbreviations. \
Matching is case-insensitive and whole-word on `term` and every variant."
),
"symbol": string(
"The notation, when the term names a quantity, in coursebank markup: $K_M$. \
Equations refer to the quantity by term id, so the symbol is written once, \
here."
),
"units": string("Units of the quantity the term names, if any."),
"exam_wording": string(
"Coined terms only: the plain wording items write instead of the label. A \
coined label is a teaching aid, not tested vocabulary, so the linter flags it \
in an item stem or option."
),
"status": entry_status(),
"tags": string_array("Free-form tags."),
"notes_private": notes_private()
}
})
}
/// One equation symbol.
fn symbol_schema() -> Value {
json!({
"type": "object",
"additionalProperties": false,
"required": ["symbol"],
"properties": {
"symbol": text("The symbol as it appears in `tex`."),
"term": string(
"Term id, when the quantity has a glossary entry; its definition and units come \
from there."
),
"meaning": string("What the symbol stands for, when it has no term."),
"units": string("Units, when the symbol has no term or the term gives none.")
}
})
}
/// One implication of an equation.
fn implication_schema() -> Value {
json!({
"type": "object",
"additionalProperties": false,
"required": ["form", "statement"],
"properties": {
"form": {
"type": "string",
"enum": relation_forms(),
"description": "direction: which way the output moves when one input rises. \
limit: what the relation gives at a boundary. scale: whether a \
stated difference is large or negligible on the relation's own \
scale. dominant_term: which term governs an observation. \
held_fixed: the reference state or normalizer. misuse: a result \
the relation cannot support."
},
"statement": required_prose("The implication as one student-facing sentence.")
}
})
}
/// One equation.
fn equation_schema() -> Value {
json!({
"type": "object",
"additionalProperties": false,
"required": ["name", "tex", "says"],
"description": "One relation students meet in this course.",
"properties": {
"name": text(
"The name students would use: the global alignment recurrence, the \
Henderson-Hasselbalch relation."
),
"tex": text(
"The relation in LaTeX, without surrounding dollar signs. Rendered as display \
math."
),
"says": required_prose(
"What the relation claims, in words, as a student should be able to state it \
with the symbols covered. Student-facing."
),
"symbols": {
"type": "array",
"items": symbol_schema(),
"description": "Every symbol in `tex`, in order of first appearance. The \
validator requires `term` or `meaning` on each."
},
"implications": {
"type": "array",
"items": implication_schema(),
"description": "What the relation says that a question can test without \
evaluating it. These are the raw material for level 2 and 3 \
targets on a relation, and the rendered 'what it tells you' list."
},
"assumes": string_array(
"Conditions that must hold for the relation to apply, one sentence each. \
Student-facing."
),
"fails_when": string_array(
"Cases where the relation breaks or misleads, one sentence each. Student-facing. \
A level 4 item often hands students a wrong result and asks which assumption \
failed."
),
"recall": {
"type": "boolean",
"description": "Students are expected to know this relation from memory. Whether \
an exam may print it is course policy \
(`policy.exam_conditions.equations`)."
},
"source": source_ref_schema(),
"status": entry_status(),
"tags": string_array("Free-form tags."),
"notes_private": notes_private()
}
})
}
/// One taught value.
fn value_schema() -> Value {
json!({
"type": "object",
"additionalProperties": false,
"required": ["name", "say"],
"description": "One number students are taught. The validator requires `value` or \
`range`.",
"properties": {
"name": text(
"The quantity, specifically: free energy per ten-fold concentration ratio at \
37 °C."
),
"value": {
"type": "number",
"description": "The value as taught (rounded as students learn it)."
},
"range": {
"type": "array",
"items": { "type": "number" },
"minItems": 2,
"maxItems": 2,
"description": "Low and high, when the course teaches a range rather than one \
value."
},
"units": string("Units, as printed."),
"say": text(
"The wording every material uses for it: 'about 6 kJ/mol'. Prose that writes \
{val-...} renders this."
),
"exact": {
"type": "number",
"description": "The unrounded value, for explanations and solutions."
},
"term": string("Term id of the quantity, when it has a glossary entry."),
"source": source_ref_schema(),
"conflicts": string_array(
"Regular expressions for variants that must not appear in any student-facing \
text or item, such as '5\\\\.7\\\\s*kJ'. Write one for every variant that has \
actually turned up."
),
"recall": {
"type": "boolean",
"description": "Students are expected to know it. An exam never prints it, and \
no option or neighbouring item may give it away."
},
"status": entry_status(),
"tags": string_array("Free-form tags."),
"notes_private": notes_private()
}
})
}
/// One sighting of a misconception.
fn evidence_schema() -> Value {
json!({
"type": "object",
"additionalProperties": false,
"required": ["kind"],
"properties": {
"kind": {
"type": "string",
"enum": [
"exam", "homework", "poll", "instructor", "literature", "textbook", "persona"
],
"description": "Where it was seen. textbook: an assigned text states or implies \
it, so the correction must name the framing it replaces rather \
than contradict the text silently. persona: a simulated \
student, the weakest evidence."
},
"detail": string("What was seen: 'Exam 2 Q23, 22% chose it.'"),
"ref": string("Citation key, for literature or textbook evidence."),
"locator": string("Where in that work.")
}
})
}
/// One named misconception.
fn misconception_schema() -> Value {
json!({
"type": "object",
"additionalProperties": false,
"required": ["belief", "correction"],
"description": "One named mistake. Slides name it, items build distractors from it, and \
reports group misses by it.",
"properties": {
"belief": required_prose(
"The wrong idea as a student holds it, in the student's words: 'a lower total \
energy always means a better structure.' Student-facing: the lecture page lists \
it under common mistakes."
),
"correction": required_prose(
"Why it fails and what is true instead, in one to three sentences. \
Student-facing."
),
"error_type": error_type_led("What kind of mistake it is, in the bank's terms."),
"evidence": {
"type": "array",
"items": evidence_schema(),
"description": "Where the misconception has been seen, strongest first."
},
"status": entry_status(),
"tags": string_array("Free-form tags."),
"notes_private": notes_private()
}
})
}
/// The four registries 2.1 adds, as the properties of whichever file holds them.
fn glossary_registries() -> serde_json::Map<String, Value> {
let mut map = serde_json::Map::new();
map.insert(
"terms".into(),
id_map(
"term",
term_schema(),
"Terms by id, `term-...`. Defined once anywhere in the course, conventionally in the \
objective file whose targets first need it. Targets list the terms they need; a \
lecture page derives its new and earlier terms from those lists.",
),
);
map.insert(
"equations".into(),
id_map(
"eq",
equation_schema(),
"Relations by id, `eq-...`. Defined once, conventionally in the objective file whose \
targets first need it.",
),
);
map.insert(
"values".into(),
id_map(
"val",
value_schema(),
"Taught numbers by id, `val-...`. Defined once; every material states a value in its \
`say` wording.",
),
);
map.insert(
"misconceptions".into(),
id_map(
"mis",
misconception_schema(),
"Named mistakes by id, `mis-...`. Defined once; targets list the ones their items \
draw on, and bank options may name the one they encode.",
),
);
map
}
/// Adds the four registries to a file schema's properties.
fn with_glossary(mut schema: Value) -> Value {
if let Some(props) = schema["properties"].as_object_mut() {
props.extend(glossary_registries());
}
schema
}
/// The notes a target carries for whoever writes items from it.
fn authoring_schema() -> Value {
json!({
"type": "object",
"additionalProperties": false,
"description": "Notes for whoever writes items, slides, or the brief from this target. \
Instructor-facing: never rendered on a student page or exported where a \
student can see it.",
"properties": {
"ceiling_item": string(
"The most demanding fair item at the ceiling, in one sentence: the evidence for \
the ceiling."
),
"supplied": string_array(
"What an item on this target hands the student: the data, the scheme, a value."
),
"constraints": string_array(
"Conditions an item's stem must meet to stay fair, which the validator cannot \
see: 'keep sequences to four bases, or supply a partly filled matrix'."
),
"number_work": string(
"The arithmetic an item needs, the operation and roughly how long it takes. \
Omit when there is none."
),
"relation_form": {
"type": "string",
"enum": relation_forms(),
"description": "When the target tests a relation without evaluating it, which \
form it uses."
},
"examples": string_array(
"Named cases that teach this target in the lecture or the readings, kept out of \
the target text so the target transfers to a case students have not seen."
)
}
})
}
/// One lecture material link.
fn material_schema() -> Value {
json!({
"type": "object",
"additionalProperties": false,
"required": ["kind", "url"],
"properties": {
"kind": {
"type": "string",
"enum": [
"slides", "brief", "notes", "notebook", "recording", "homework", "other"
]
},
"title": string("Link text. Defaults to the kind."),
"url": text("Where it lives.")
}
})
}
/// How exams are sat.
fn exam_conditions_schema() -> Value {
let formats: Vec<&str> = Format::ALL.iter().map(|f| f.as_str()).collect();
json!({
"type": "object",
"additionalProperties": false,
"description": "How exams are sat, as students were told. Pipelines and the linter read \
these instead of assuming one course's rules.",
"properties": {
"closed_book": { "type": "boolean" },
"calculator": {
"type": "boolean",
"description": "false: no item may need arithmetic beyond a few seconds, and \
`target_text_forbid` usually bans words that promise a \
calculation."
},
"equations": {
"type": "string",
"enum": ["never_printed", "sheet", "in_stem"],
"description": "Whether a relation an item turns on may appear: never (students \
bring the relation), on a supplied sheet, or in the stem."
},
"formats": {
"type": "array",
"items": { "type": "string", "enum": strings(&formats) },
"description": "Item formats exams use now. Ceilings are still set by the most \
demanding fair item in any format."
},
"seconds_per_item": {
"type": "number",
"exclusiveMinimum": 0.0,
"description": "The time budget an item is written to."
}
}
})
}
/// The named default blueprints.
fn policy_blueprints_schema() -> Value {
json!({
"type": "object",
"description": "Named default blueprints (module, final), as published to students. An \
assessment's own `blueprint` wins.",
"additionalProperties": {
"type": "object",
"additionalProperties": false,
"required": ["level_counts"],
"properties": {
"level_counts": {
"type": "object",
"additionalProperties": { "type": "integer", "minimum": 0 },
"description": "Scored items at each level, keyed by level number."
},
"bonus_counts": {
"type": "object",
"additionalProperties": { "type": "integer", "minimum": 0 }
},
"minutes": { "type": "number", "exclusiveMinimum": 0.0 }
}
}
})
}
/// The course's names for the levels.
fn policy_levels_schema() -> Value {
json!({
"type": "object",
"description": "The course's own names and one-line descriptions for levels 1 to 5, as \
students were told them. Lecture pages label ceilings with these; \
absent, the generic Bloom names are used.",
"propertyNames": { "pattern": "^[1-5]$" },
"additionalProperties": {
"type": "object",
"additionalProperties": false,
"required": ["name"],
"properties": {
"name": text("Definitions, Concepts, Application ..."),
"description": string("One line, as published.")
}
}
})
}
@@ -256,6 +800,25 @@ fn course_identity_schema() -> Value {
/// The schema for the course-wide policy block.
fn policy_schema() -> Value {
let mut schema = policy_base_schema();
if let Some(props) = schema["properties"].as_object_mut() {
props.insert("exam_conditions".into(), exam_conditions_schema());
props.insert("blueprints".into(), policy_blueprints_schema());
props.insert("levels".into(), policy_levels_schema());
props.insert(
"target_text_forbid".into(),
string_array(
"Regular expressions that must not match objective or target text, with the \
reason in a comment beside them (for example '\\\\bcalculat' when exams are \
calculator-free). The linter reports every match.",
),
);
}
schema
}
/// The 2.0 policy fields, which [`policy_schema`] extends.
fn policy_base_schema() -> Value {
json!({
"type": "object",
"additionalProperties": false,
@@ -369,6 +932,17 @@ fn lecture_schema() -> Value {
"description": "Readings assigned with this lecture, in the order you assign \
them. A plain string is the pre-schema form and still loads.",
"items": reading_schema()
},
"description": prose(
"The lecture in two to four sentences, student-facing: what it covers and the \
arc its objectives follow. The lecture page opens with it."
),
"materials": {
"type": "array",
"items": material_schema(),
"description": "Links the lecture page lists beside the readings: slides, the \
brief, notebooks, the recording. `slides_url` is the older \
single-link form and still loads."
}
}
})
@@ -376,6 +950,44 @@ fn lecture_schema() -> Value {
/// The schema for one learning target.
fn target_schema() -> Value {
let mut schema = target_base_schema();
if let Some(props) = schema["properties"].as_object_mut() {
props.insert(
"explanation".into(),
prose(
"The canonical account a student who has met this target could give, in two to \
four sentences: the rule or mechanism, what changes the outcome, and when it \
holds. Student-facing. Not a worked example. The lecture brief expands it; \
slides and items are checked against it.",
),
);
props.insert(
"terms".into(),
string_array(
"Term ids a student needs to meet this target. A term is new on the first \
lecture (in teaching order) whose targets list it, and listed as earlier \
vocabulary on later ones.",
),
);
props.insert(
"equations".into(),
string_array("Equation ids this target turns on."),
);
props.insert("values".into(), string_array("Value ids this target uses."));
props.insert(
"misconceptions".into(),
string_array(
"Misconception ids an item on this target is most likely to draw on. \
Distractors are built from them, and the lecture names them.",
),
);
props.insert("authoring".into(), authoring_schema());
}
schema
}
/// The 2.0 target fields, which [`target_schema`] extends.
fn target_base_schema() -> Value {
json!({
"type": "object",
"required": ["text", "objective"],
@@ -420,6 +1032,11 @@ fn objective_schema() -> Value {
"additionalProperties": false,
"properties": {
"text": text("The objective as a student would read it. Start with a verb."),
"description": prose(
"Two to four sentences, student-facing: what this objective is about, why it \
matters, and what it builds on or leads to. Rendered under the objective on the \
lecture page."
),
"unit": { "type": "string" },
"lectures": string_array("Lecture ids that cover this."),
"order": {
@@ -543,9 +1160,16 @@ fn reading_mapping_schema() -> Value {
reading list resolved from an objective would send a student the same six \
sections whichever part of it they missed."
),
"summary": text("What the section contains."),
"focus": text("What to take from it. This is the sentence a student report quotes."),
"skip": text("What to gloss, and why it is out of scope."),
"summary": required_prose("What the section contains."),
"focus": required_prose(
"What to take from it. This is the sentence a student report quotes."
),
"skip": required_prose("What to gloss, and why it is out of scope."),
"minutes": {
"type": "integer",
"minimum": 1,
"description": "Estimated reading time, for the lecture page's workload line."
},
"text": text("A pre-schema citation string, held unparsed.")
}
})
@@ -567,12 +1191,18 @@ fn stimulus_schema() -> Value {
/// The course schema.
fn course_schema() -> Value {
with_glossary(course_base_schema())
}
/// The 2.0 sections of the course schema, which [`course_schema`] extends.
fn course_base_schema() -> Value {
json!({
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": format!("{BASE}/course.schema.json"),
"title": "coursebank course file",
"description": "Course identity, policy, and the registries that item and assessment \
files reference by id.",
files reference by id: objectives, targets, lectures, references, \
stimuli, terms, equations, values, and misconceptions.",
"type": "object",
"required": ["course"],
"additionalProperties": false,
@@ -675,14 +1305,43 @@ fn lecture_fragment_schema() -> Value {
})
}
/// The schema for `glossary.yaml`.
fn glossary_fragment_schema() -> Value {
with_glossary(json!({
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": format!("{BASE}/glossary.schema.json"),
"title": "coursebank glossary file",
"description": "Terms, equations, values, and misconceptions that belong to no single \
objective: cross-cutting entries, and everything `coursebank migrate \
glossary` brings in from terms.yaml and values.yaml until each entry is \
moved to the objective file whose targets first need it. A fragment of \
the course file, merged on load.",
"type": "object",
"additionalProperties": false,
"properties": {
"schema_version": {
"type": ["string", "number"],
"description": "Declared in course.yaml; fragments inherit it."
}
}
}))
}
/// The schema for one file under `objectives/`.
fn objective_fragment_schema() -> Value {
with_glossary(objective_fragment_base_schema())
}
/// The 2.0 sections of an objective file, which [`objective_fragment_schema`]
/// extends.
fn objective_fragment_base_schema() -> Value {
json!({
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": format!("{BASE}/objective.schema.json"),
"title": "coursebank objective file",
"description": "One learning objective and the learning targets it decomposes into. A \
fragment of the course file, merged on load.",
"description": "One learning objective, the learning targets it decomposes into, and \
the terms, equations, values, and misconceptions its targets first \
need. A fragment of the course file, merged on load.",
"type": "object",
"required": ["learning_objectives"],
"additionalProperties": false,
@@ -746,7 +1405,16 @@ fn option_schema() -> Value {
"type": "string",
"description": "The specific wrong belief that leads here. This text is what \
student reports use, so write it as a completion of 'students \
pick this when ...'."
pick this when ...'. Optional when `misconception_id` is set: \
the registry's `belief` is used."
},
"misconception_id": {
"type": "string",
"pattern": "^mis-[a-z0-9]+(-[a-z0-9]+)*$",
"description": "The registry misconception this distractor encodes. Reports \
group misses by it across items; the option's own \
`misconception` text, when present, overrides the registry's \
wording for this item."
},
"error_type": error_type(),
"defensible": {
+3 -18
View File
@@ -425,10 +425,6 @@ mod tests {
"L1.1".into(),
Lecture {
title: "Enthalpy".into(),
date: None,
unit: None,
slides_url: None,
teaches: Vec::new(),
readings: vec![
Reading {
reference: Some("kuriyan2013molecules".into()),
@@ -449,6 +445,7 @@ mod tests {
..Reading::default()
},
],
..Lecture::default()
},
);
c
@@ -456,16 +453,7 @@ mod tests {
/// The non-defaulted half of an objective, so the fixtures stay short.
fn objective_defaults() -> Objective {
Objective {
text: String::new(),
unit: None,
lectures: Vec::new(),
order: None,
level_ceiling: None,
prerequisites: Vec::new(),
tags: Vec::new(),
assessed: true,
}
Objective::default()
}
#[test]
@@ -553,10 +541,7 @@ After this lecture, you should be able to do the following.
objective: "lo-binding".into(),
lectures: objective.lectures,
order: Some(order),
level_ceiling: None,
prerequisites: Vec::new(),
tags: Vec::new(),
assessed: true,
..Target::default()
},
);
}
+1
View File
@@ -1263,6 +1263,7 @@ mod tests {
explanation: Some("Only at constant volume.".into()),
hint: Some("Reconsider what stays constant in an open flask.".into()),
misconception: Some("Uses the constant-volume result.".into()),
misconception_id: None,
error_type: None,
defensible: false,
defense: None,
+314 -18
View File
@@ -23,6 +23,7 @@
//! belongs to the course and the administration, never to the item.
pub mod fragment;
pub mod glossary;
use std::collections::BTreeMap;
use std::fmt;
@@ -34,13 +35,20 @@ use serde::{Deserialize, Deserializer, Serialize, Serializer};
use crate::date::Date;
use crate::error::{Error, Result};
use crate::taxonomy::Level;
use crate::taxonomy::{Format, Level};
use crate::yaml;
use fragment::Section;
use glossary::{Authoring, Equation, Material, Misconception, Term, Value};
/// The schema version this build of the tool writes.
pub const SCHEMA_VERSION: &str = "2.0";
///
/// 2.1 is additive: it adds the term, equation, value, and misconception
/// registries ([`glossary`]), short student-facing text on objectives, targets,
/// and lectures, and per-course exam conditions to [`Policy`]. Nothing is renamed
/// or removed and nothing already present becomes required, so a 2.0 course
/// loads and validates unchanged.
pub const SCHEMA_VERSION: &str = "2.1";
/// The schema major versions this build can read.
///
@@ -112,6 +120,22 @@ pub struct CourseFile {
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub stimuli: BTreeMap<String, Stimulus>,
/// Terms, keyed by id such as `term-gap-penalty`. See [`glossary`].
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub terms: BTreeMap<String, Term>,
/// Equations, keyed by id such as `eq-global-recurrence`.
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub equations: BTreeMap<String, Equation>,
/// Taught numbers, keyed by id such as `val-per-decade`.
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub values: BTreeMap<String, Value>,
/// Named mistakes, keyed by id such as `mis-only-matches-count`.
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub misconceptions: BTreeMap<String, Misconception>,
/// Which file defined each id, relative to the course root.
///
/// Populated by [`fragment::assemble`] and empty for a course parsed
@@ -193,6 +217,169 @@ pub struct Policy {
/// student or an instructor actually acts on.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub grade_scale: Vec<GradeBand>,
/// How exams are sat, as students were told.
///
/// Pipelines and the linter read these instead of assuming one course's
/// rules: the objectives prompt used to hard-code closed book, no
/// calculator, no printed equations, and two minutes an item.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub exam_conditions: Option<ExamConditions>,
/// Named default blueprints, such as `module` and `final`, as published to
/// students. An assessment's own blueprint wins.
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub blueprints: BTreeMap<String, PolicyBlueprint>,
/// The course's own names and one-line descriptions for levels 1 to 5, as
/// students were told them. A lecture page labels ceilings with these, and
/// falls back to the generic names when one is absent.
#[serde(
default,
deserialize_with = "level_keyed",
skip_serializing_if = "BTreeMap::is_empty"
)]
pub levels: BTreeMap<String, LevelName>,
/// Regular expressions that must not match objective or target text.
///
/// The objectives prompt's ban on "compute, calculate, estimate" was one
/// course's rule written into a shared tool; this makes it one course's
/// setting. The linter reports every match, case-insensitively.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub target_text_forbid: Vec<String>,
}
/// How exams are sat.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ExamConditions {
/// Whether exams are closed book.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub closed_book: Option<bool>,
/// Whether a calculator is allowed. When it is not, no item may need
/// arithmetic beyond a few seconds.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub calculator: Option<bool>,
/// Whether a relation an item turns on may appear.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub equations: Option<EquationPolicy>,
/// Item formats exams use now.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub formats: Vec<Format>,
/// The time budget an item is written to, in seconds.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub seconds_per_item: Option<f64>,
}
/// Whether an exam shows students the relations its items turn on.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum EquationPolicy {
/// Never: students bring the relation.
NeverPrinted,
/// On a supplied equation sheet.
Sheet,
/// In the stem of the item that needs it.
InStem,
}
/// A named default blueprint.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct PolicyBlueprint {
/// Scored items at each level, keyed by level number.
#[serde(deserialize_with = "level_keyed")]
pub level_counts: BTreeMap<String, u32>,
/// Bonus items at each level, keyed by level number.
#[serde(
default,
deserialize_with = "level_keyed",
skip_serializing_if = "BTreeMap::is_empty"
)]
pub bonus_counts: BTreeMap<String, u32>,
/// The time allowed, in minutes.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub minutes: Option<f64>,
}
/// The course's name for one level.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct LevelName {
/// The name, as published: `Definitions`, `Application`.
pub name: String,
/// One line, as published.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub description: Option<String>,
}
impl Policy {
/// The name a lecture page gives a level: the course's own, else the
/// generic one.
///
/// # Arguments
///
/// * `level` - the level.
///
/// # Returns
///
/// The display name.
pub fn level_name(&self, level: Level) -> String {
self.levels
.get(&level.code().to_string())
.map(|l| l.name.clone())
.unwrap_or_else(|| level.name().to_string())
}
}
/// Reads a map keyed by level number, whether YAML wrote the keys as `'1'` or
/// as `1`.
///
/// JSON Schema can only describe string keys, so the schema and the examples
/// quote them; an unquoted key is the natural thing to type, and loads too.
fn level_keyed<'de, D, T>(d: D) -> std::result::Result<BTreeMap<String, T>, D::Error>
where
D: Deserializer<'de>,
T: Deserialize<'de>,
{
/// One key, as a string or an integer.
struct Key(String);
impl<'de> Deserialize<'de> for Key {
fn deserialize<D: Deserializer<'de>>(d: D) -> std::result::Result<Key, D::Error> {
struct V;
impl Visitor<'_> for V {
type Value = Key;
fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str("a level number")
}
fn visit_str<E: de::Error>(self, v: &str) -> std::result::Result<Key, E> {
Ok(Key(v.to_string()))
}
fn visit_u64<E: de::Error>(self, v: u64) -> std::result::Result<Key, E> {
Ok(Key(v.to_string()))
}
fn visit_i64<E: de::Error>(self, v: i64) -> std::result::Result<Key, E> {
Ok(Key(v.to_string()))
}
}
d.deserialize_any(V)
}
}
impl PartialEq for Key {
fn eq(&self, other: &Key) -> bool {
self.0 == other.0
}
}
impl Eq for Key {}
impl PartialOrd for Key {
fn partial_cmp(&self, other: &Key) -> Option<std::cmp::Ordering> {
Some(self.cmp(other))
}
}
impl Ord for Key {
fn cmp(&self, other: &Key) -> std::cmp::Ordering {
self.0.cmp(&other.0)
}
}
let raw: BTreeMap<Key, T> = BTreeMap::deserialize(d)?;
Ok(raw.into_iter().map(|(k, v)| (k.0, v)).collect())
}
/// One letter-grade band.
@@ -250,6 +437,10 @@ impl Default for Policy {
mastery_threshold: mastery_default(),
min_items_for_mastery: 2,
grade_scale: Vec::new(),
exam_conditions: None,
blueprints: BTreeMap::new(),
levels: BTreeMap::new(),
target_text_forbid: Vec::new(),
}
}
}
@@ -301,11 +492,16 @@ pub struct Unit {
}
/// A lecture or class session.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Lecture {
/// Human title.
pub title: String,
/// The lecture in two to four sentences: what it covers and the arc its
/// objectives follow. Student-facing; the lecture page opens with it, and it
/// may hold brace references.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub description: Option<String>,
/// The date it ran, when known.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub date: Option<Date>,
@@ -327,6 +523,11 @@ pub struct Lecture {
/// Assigned readings for the session, in the order you assign them.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub readings: Vec<Reading>,
/// Links the lecture page lists beside the readings: slides, the brief,
/// notebooks, the recording. [`Lecture::slides_url`] is the older
/// single-link form and still loads.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub materials: Vec<Material>,
}
/// A work the course cites: a textbook, an article, a dataset, a recording.
@@ -591,6 +792,8 @@ pub struct Reading {
pub focus: Option<String>,
/// What to gloss, and why it is out of scope.
pub skip: Option<String>,
/// Estimated reading time in minutes, for the lecture page's workload line.
pub minutes: Option<u32>,
/// A reading written as a bare string before this schema existed, held
/// unparsed.
pub text: Option<String>,
@@ -684,6 +887,9 @@ impl Serialize for Reading {
if let Some(v) = &self.skip {
map.serialize_entry("skip", v)?;
}
if let Some(v) = &self.minutes {
map.serialize_entry("minutes", v)?;
}
if let Some(v) = &self.text {
map.serialize_entry("text", v)?;
}
@@ -721,6 +927,8 @@ impl<'de> Deserialize<'de> for Reading {
#[serde(default)]
skip: Option<String>,
#[serde(default)]
minutes: Option<u32>,
#[serde(default)]
text: Option<String>,
}
@@ -751,6 +959,7 @@ impl<'de> Deserialize<'de> for Reading {
summary: m.summary,
focus: m.focus,
skip: m.skip,
minutes: m.minutes,
text: m.text,
})
}
@@ -794,6 +1003,14 @@ pub struct Objective {
/// The objective as you would state it to students. Reports quote this
/// verbatim, so write it in the second person and start with a verb.
pub text: String,
/// Two to four sentences under the objective on the lecture page: what it
/// is about, why it matters, and what it builds on or leads to.
/// Student-facing; may hold brace references.
///
/// The course guide asks students to read targets as a map. This is the
/// legend.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub description: Option<String>,
/// The unit it belongs to.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub unit: Option<String>,
@@ -904,6 +1121,92 @@ pub struct Target {
/// unassessed objective exempts its targets regardless of this.
#[serde(default = "yes")]
pub assessed: bool,
/// The canonical account a student who has met this target could give, in
/// two to four sentences: the rule or mechanism, what changes the outcome,
/// and when it holds. Student-facing; may hold brace references.
///
/// Not a worked example. The lecture brief expands it, and slides and
/// items are checked against it. A student report quotes it under a missed
/// question, as what meeting the target looks like.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub explanation: Option<String>,
/// Term ids a student needs to meet this target.
///
/// A term is new on the first lecture, in teaching order, whose targets
/// list it, and listed as earlier vocabulary on later ones.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub terms: Vec<String>,
/// Equation ids this target turns on.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub equations: Vec<String>,
/// Value ids this target uses.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub values: Vec<String>,
/// Misconception ids an item on this target is most likely to draw on.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub misconceptions: Vec<String>,
/// Notes for whoever writes items, slides, or the brief from this target.
/// Instructor-facing: never rendered for students.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub authoring: Option<Authoring>,
}
impl Default for Objective {
fn default() -> Objective {
Objective {
text: String::new(),
description: None,
unit: None,
lectures: Vec::new(),
order: None,
level_ceiling: None,
prerequisites: Vec::new(),
tags: Vec::new(),
assessed: true,
}
}
}
impl Default for Target {
fn default() -> Target {
Target {
text: String::new(),
objective: String::new(),
lectures: Vec::new(),
order: None,
level_ceiling: None,
prerequisites: Vec::new(),
tags: Vec::new(),
assessed: true,
explanation: None,
terms: Vec::new(),
equations: Vec::new(),
values: Vec::new(),
misconceptions: Vec::new(),
authoring: None,
}
}
}
impl Target {
/// The ids this target lists in one registry.
///
/// # Arguments
///
/// * `kind` - which registry.
///
/// # Returns
///
/// The listed ids, empty for the objective and target kinds.
pub fn listed(&self, kind: glossary::RefKind) -> &[String] {
match kind {
glossary::RefKind::Term => &self.terms,
glossary::RefKind::Equation => &self.equations,
glossary::RefKind::Value => &self.values,
glossary::RefKind::Misconception => &self.misconceptions,
glossary::RefKind::Objective | glossary::RefKind::Target => &[],
}
}
}
/// The prefix an objective id is expected to carry.
@@ -2158,11 +2461,8 @@ impl CourseFile {
"L01".to_string(),
Lecture {
title: "Course introduction".to_string(),
date: None,
unit: Some("u-intro".to_string()),
slides_url: None,
teaches: Vec::new(),
readings: Vec::new(),
..Lecture::default()
},
);
let mut los = BTreeMap::new();
@@ -2174,9 +2474,7 @@ impl CourseFile {
lectures: vec!["L01".to_string()],
order: Some(1),
level_ceiling: Some(Level::Understand),
prerequisites: Vec::new(),
tags: Vec::new(),
assessed: true,
..Objective::default()
},
);
// One target as well, because the two tiers are easier to understand
@@ -2190,10 +2488,7 @@ impl CourseFile {
objective: "lo-example".to_string(),
lectures: vec!["L01".to_string()],
order: Some(1),
level_ceiling: None,
prerequisites: Vec::new(),
tags: Vec::new(),
assessed: true,
..Target::default()
},
);
CourseFile {
@@ -2217,6 +2512,10 @@ impl CourseFile {
learning_targets: targets,
references: BTreeMap::new(),
stimuli: BTreeMap::new(),
terms: BTreeMap::new(),
equations: BTreeMap::new(),
values: BTreeMap::new(),
misconceptions: BTreeMap::new(),
origins: BTreeMap::new(),
}
}
@@ -2580,10 +2879,7 @@ lectures:
unit: None,
lectures: vec!["L1.1".to_string()],
order: Some(3),
level_ceiling: None,
prerequisites: Vec::new(),
tags: Vec::new(),
assessed: true,
..Objective::default()
},
);
assert_eq!(c.targets_without_readings(), vec!["lo-orphan"]);
+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,
})
}
+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"]);
}
}
+8
View File
@@ -242,6 +242,14 @@ pub struct Choice {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub misconception: Option<String>,
/// The registry misconception this distractor encodes, `mis-...`.
///
/// Reports group misses by it across items. The option's own
/// [`Choice::misconception`] text, when present, overrides the registry's
/// `belief` for this item; when absent, reports use the registry's.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub misconception_id: Option<String>,
/// The category of that error.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub error_type: Option<ErrorType>,
+6
View File
@@ -49,6 +49,12 @@ impl Layout {
self.root.join(crate::course::fragment::REFERENCES_FILE)
}
/// `glossary.yaml`, the terms, equations, values, and misconceptions that
/// belong to no single objective.
pub fn glossary_file(&self) -> PathBuf {
self.root.join(crate::course::fragment::GLOSSARY_FILE)
}
/// Directory holding one file per lecture.
pub fn lectures(&self) -> PathBuf {
self.root.join("lectures")