# 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.