Files
coursebank/docs/design/2.1/SCHEMA-CHANGES.md
T
alexmandClaude 51a2fd235f 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>
2026-11-16 11:55:18 -05:00

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; assumes and fails_when are 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

  1. 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/).
  2. 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.
  3. 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 no introduced_in to keep in sync.
  4. Student-facing and instructor-facing fields are separate. Every new prose field is marked as one or the other in its description. authoring and notes_private are never rendered on a student page or exported where a student can see them.
  5. 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.0e59 as a string; the examples write 1.0e+59, which both 1.1 and 1.2 parsers read as a number.
  • The schemas carry their documentation in description strings, which come from Rust doc comments. Keep the wording; it is what an author sees in an editor.