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>
17 KiB
coursebank 2.1: what changes in the schemas, and why
This is the specification for coursebank 2.1. schemas/ holds the target JSON Schemas; examples/ holds course fragments that must validate (2.0 and 2.1); prototype/check21.py is an executable sketch of every new validation rule, lint, and lecture-page derivation, with a self-test that breaks the example once per rule. Where this document and the prototype disagree, this document wins.
Why
A lecture today is specified by its objectives, its targets (each with a ceiling), and its readings. Everything else a lecture provides lives in files coursebank cannot see: the course's terms and numbers in terms.yaml and values.yaml, the named mistakes in each pipeline's notes, the equations nowhere at all. The lecture page therefore shows students half of what they need to study, and the slide, brief, and item pipelines each keep their own copy of the rest, which drifts.
The course guide (Learning to Learn) makes promises the 2.0 format cannot carry:
- The target list is the study tool. "The target list guides the lecture, readings, homework, and exam." A target says what to do; 2.1 adds the short canonical account of it (
explanation) and the vocabulary, relations, numbers, and mistakes it turns on. - Relations are understood, not computed. "If you understand an equation well enough to say what each part does and why, you can answer these questions." An equation entry records what it says in words, what each symbol means, what it implies (direction, limit, scale, which term dominates, what is held fixed, how it is misused), what it assumes, and when it fails. The guide tells students that a level 4 question often asks which assumption failed;
assumesandfails_whenare where that comes from. - Common mistakes become distractors. "When I point out what students often get wrong in class and explain why, I'm showing you how I come up with wrong answers for tests." A misconception becomes a registry entry with an id: the lecture page lists it, slides name it, item options point at it, and reports can group misses by it across items.
- Numbers are stated one way. The values file exists because the same number drifted across briefs, slides, and banks. 2.1 moves it into the registry, and prose can write
{val-...}so every page renders the one approved wording. - Several courses. The objectives prompt hard-codes one course's exam conditions (closed book, no calculator, no printed equations, multiple choice, two minutes an item) and blueprint. 2.1 puts them in
policy, so pipelines and lints read each course's own rules.
Principles
- Additive. No field is renamed or removed, and no new field is required on an existing object. Every 2.0 course validates unchanged (
examples/v20/). - Defined once, by id. Each new registry is a map keyed by id, like
learning_targets, merged on load from any fragment. An id is defined in exactly one file, and ids are unique across all registries. - Targets point at the glossary; nothing points back. A target lists the terms, equations, values, and misconceptions it needs. Which lecture introduces a term is derived (the first lecture, in teaching order, whose targets list it), the same way an objective's lectures are derived from
teaches. There is nointroduced_into keep in sync. - Student-facing and instructor-facing fields are separate. Every new prose field is marked as one or the other in its description.
authoringandnotes_privateare never rendered on a student page or exported where a student can see them. - Short canonical text. The registry holds a few sentences per objective and target, one-sentence definitions, and one-sentence statements about each equation. Long-form prose stays in the lecture brief, which is checked against the registry.
New registries
Ids carry a prefix so any id in an item, a reading, a report, or a brace reference says which registry it belongs to without a lookup: term-, eq-, val-, mis- (alongside the existing lo-, t-, q-, o-). The schemas state the prefix as a propertyNames pattern; if the schema generator cannot express that, the validator enforces it.
terms: (term-...)
| field | required | reader | what and why |
|---|---|---|---|
term |
yes | student | the word or phrase as the course writes it |
definition |
yes | student | one plain sentence that does not use the term itself (lint W2104) |
kind |
both | standard (default), renamed, coined, carried over from terms.yaml: whether a student can look it up |
|
textbook |
student | the names the assigned texts use, {term, ref, locator}; a renamed or coined term without one draws W2102 |
|
variants |
tools | other surface forms, for matching in slides, briefs, and items | |
symbol, units |
student | the notation and units when the term names a quantity; equations refer to the quantity by term id, so the symbol is written once | |
exam_wording |
tools | coined terms only: what items write instead of the label (lint W2103, W2105) | |
status, tags, notes_private |
see "Status" below |
equations: (eq-...)
| field | required | reader | what and why |
|---|---|---|---|
name |
yes | student | the name students would use |
tex |
yes | student | LaTeX without dollar signs, rendered as display math |
says |
yes | student | what the relation claims, in words, with the symbols covered |
symbols |
student | every symbol, in order, with a term id or a meaning (E2103), and units |
|
implications |
student | {form, statement}, form one of direction, limit, scale, dominant_term, held_fixed, misuse: the six things a question can ask about a relation without evaluating it, from the objectives prompt's "six ways to test a relation". They are the raw material for level 2 and 3 targets, and a ceiling-3 target that turns on an equation with none draws W2111 |
|
assumes, fails_when |
student | conditions for the relation, and where it breaks; the raw material for level 4 | |
recall |
both | students are expected to know it; whether an exam prints it is policy.exam_conditions.equations |
|
source |
both | {ref, locator} |
values: (val-...)
The fields of values.yaml, with two changes: lectures is gone (derived from the targets that list the value), and term links the quantity to its glossary entry.
| field | required | what and why |
|---|---|---|
name, say |
yes | the quantity, and the one wording every material uses; {val-...} in prose renders say |
value or range |
one of them (E2104) | the number as taught, or [low, high] |
units, exact, term, source |
exact is the unrounded value for solutions; a value with no source draws W2106 |
|
conflicts |
regular expressions for variants that must not appear; must compile (E2107); a match in any student-facing prose or item text draws W2107 | |
recall |
students must know it; an item that prints it draws W2110 |
misconceptions: (mis-...)
| field | required | reader | what and why |
|---|---|---|---|
belief |
yes | student | the wrong idea as a student holds it; listed under common mistakes on the lecture page |
correction |
yes | student | why it fails and what is true instead |
error_type |
tools | the bank's existing enum, so a registry entry and a distractor classify mistakes the same way | |
evidence |
instructor | {kind, detail, ref, locator}, kind one of exam, homework, poll, instructor, literature, textbook, persona. textbook matters: when an assigned text states the misconception, the correction must name the framing it replaces |
Status
Every new registry entry may carry status: proposed | approved (absent means approved). A pipeline that adds an entry marks it proposed; the instructor approves by deleting the line. Checks treat proposed entries exactly like approved ones, and the linter reports how many are waiting (I2113). This is the terms.yaml convention, kept.
Where entries are defined
Any fragment may define glossary entries. The convention, reported but not enforced (I2112), is the objective file whose targets first need the entry. Cross-cutting entries, and everything migrated from terms.yaml and values.yaml, go in a new fragment, glossary.yaml (schemas/glossary.schema.json), until a pipeline or the instructor moves each one. objective.schema.json gains the four registries; course.schema.json gains them for the merged course.
Changes to existing objects
| object | new field | reader | why |
|---|---|---|---|
| objective | description |
student | two to four sentences under the objective on the lecture page: what it is about, why it matters, what it builds on or leads to. The guide asks students to read targets as a map; this is the legend |
| target | explanation |
student | the canonical account a student who has met the target could give, in two to four sentences. Not a worked example. The brief expands it; slides and items are checked against it |
| target | terms, equations, values, misconceptions |
tools | id lists; they drive the lecture page's glossary sections, the "new here" versus "from earlier" split, and the checks (E2102, W2101, W2109) |
| target | authoring |
instructor | ceiling_item (the most demanding fair item, the evidence for the ceiling), supplied (what the stem hands over), constraints (stem conditions that keep the item fair, which the validator cannot see), number_work, relation_form, examples (the named cases kept out of the target text). These are the per-target judgments the objectives prompt asks for and then loses in chat output; 2.1 keeps them where the item writer will look |
| lecture | description |
student | the lecture in two to four sentences; the lecture page opens with it |
| lecture | materials |
student | {kind, title, url} links (slides, brief, notes, notebook, recording, homework). slides_url still loads |
| reading | minutes |
student | estimated reading time, for a workload line on the page |
| bank option | misconception_id |
tools | the registry misconception the distractor encodes (E2108). The option's own misconception text, when present, overrides the registry's belief for that item; when absent, reports use the registry's |
| policy | exam_conditions |
tools | closed_book, calculator, equations (never_printed, sheet, in_stem), formats, seconds_per_item |
| policy | blueprints |
tools | named default blueprints (module, final), each {level_counts, bonus_counts, minutes}. An assessment's own blueprint still wins |
| policy | levels |
student | the course's names and one-line descriptions for levels 1 to 5, as students were told them; the lecture page labels ceilings with them |
| policy | target_text_forbid |
tools | regular expressions that must not match objective or target text (W2108); the objectives prompt's ban on "compute, calculate, estimate" becomes one course's setting |
Unchanged: assessment, measurements, calibration. references changes only its version line. schema_version is 2.1.
Brace references
Any student-facing prose field may reference an entry in braces: {term-...}, {eq-...}, {val-...}, {mis-...}, {t-...}, {lo-...}. The 2.0 rule (a {t-...} in a reading's prose renders the target's number) extends to all of them:
| reference | renders as |
|---|---|
{term-...} |
the term's term, linked to its glossary entry |
{eq-...} |
the equation's name, linked to its display block |
{val-...} |
the value's say |
{mis-...} |
the misconception's belief, quoted |
{t-...}, {lo-...} |
the target's or objective's number (T 4, as today) |
Every reference must resolve (E2106). A target's explanation that names a term in braces should list that term in terms or inherit it through a prerequisite target (W2109).
Rules
The codes below are the prototype's; map them onto coursebank's own code scheme and keep a table.
Errors
| code | rule |
|---|---|
| E2101 | an id is defined in two files, in any registry (the 2.0 rule, extended to the new registries; ids are unique across all of them) |
| E2102 | a target's terms, equations, values, or misconceptions names an undeclared entry of that registry |
| E2103 | an equation symbol names an undeclared term, or has neither term nor meaning |
| E2104 | a value has neither value nor range, a range runs high to low, or its term is undeclared |
| E2105 | a ref in a new registry (source, textbook, evidence) is not in references |
| E2106 | a brace reference in student-facing prose does not resolve |
| E2107 | a conflicts or target_text_forbid pattern does not compile |
| E2108 | a bank option's misconception_id is undeclared |
Lint
| code | rule |
|---|---|
| W2101 | a glossary entry nothing needs: no target, equation symbol, value, or item option lists it |
| W2102 | a renamed or coined term with no textbook name |
| W2103 | a coined term with no exam_wording |
| W2104 | a definition that uses the term it defines (or a variant) |
| W2105 | a coined term (or variant) in an item's stem or option |
| W2106 | a value with no source |
| W2107 | a value's conflicts pattern matches student-facing prose or item text |
| W2108 | objective or target text matches policy.target_text_forbid |
| W2109 | a target's explanation names a term in braces that it neither lists nor inherits from a prerequisite target |
| W2110 | an item's stem or option prints a recall: true value |
| W2111 | a target with ceiling 3 or above turns on an equation that lists no implications |
| I2112 | a glossary entry defined in an objective file other than the one whose targets first need it (a convention, reported as a note) |
| I2113 | proposed entries waiting for approval, counted |
These replace checks that live in the pipelines today (the slide linter's W374 and W375, the bank linter's W334, W804, W805, the brief linter's terms and values checks), so all three pipelines can call coursebank lint instead of each reading terms.yaml and values.yaml itself.
Derived data and rendering
Teaching order is the existing one: lectures in order, objectives in each lecture's teaches order.
A glossary entry's first lecture is the first lecture, in teaching order, with a target that lists it. A lecture's new terms are those whose first lecture it is; its earlier terms are the rest of what its targets list, each shown with the lecture that introduced it.
The lecture page shows, in order: the description; each objective with its description, its targets sorted by ceiling then id (the 2.0 rule) with each target's explanation and the ceiling labelled by policy.levels; new terms (with symbol, definition, and the textbook name for renamed and coined terms); earlier terms, linked; the equations its targets turn on (display, says, symbols, implications, assumes, fails when); the values (say, marked when students must know it); common mistakes (belief, correction); readings (with minutes); materials. examples/v21/lecture-page-preview.md shows the content and order the prototype derives for the example lecture; the layout is the renderer's.
A course glossary page lists every term alphabetically with its definition and its first lecture, and every equation and value with theirs.
Student reports gain two things: a missed item's target explanation (what meeting it looks like), and, when the chosen option has a misconception_id, the misconception's correction; misses that share a misconception across items are grouped under it.
Never rendered for students: authoring, notes_private, evidence, conflicts, status.
Migration
coursebank migrate glossary --terms terms.yaml --values values.yaml writes glossary.yaml:
| from | to |
|---|---|
terms[].id: decade |
terms: term-decade: (prefix added; report the rename) |
course, variants, kind, textbook, exam_wording, status |
the same fields (course becomes term) |
meaning |
definition |
first |
dropped: derived from targets. Report each term whose old first differs from the derived first lecture, and each term no target lists yet |
values[].id: per-decade |
values: val-per-decade: |
name, value, units, say, exact, source, conflicts, recall, status |
the same fields |
lectures |
dropped: derived. Report differences the same way |
The migration leaves terms.yaml and values.yaml in place; the pipelines switch to the registry when it validates. Linking existing targets to the migrated entries is the new pipeline's job, not the migration's.
Notes
- YAML 1.1 parsers (Python's PyYAML) read
1.0e59as a string; the examples write1.0e+59, which both 1.1 and 1.2 parsers read as a number. - The schemas carry their documentation in
descriptionstrings, which come from Rust doc comments. Keep the wording; it is what an author sees in an editor.