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

@@ -0,0 +1,703 @@
{
"$id": "https://coursebank.dev/schema/objective.schema.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"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.",
"properties": {
"equations": {
"additionalProperties": {
"additionalProperties": false,
"description": "One relation students meet in this course.",
"properties": {
"assumes": {
"description": "Conditions that must hold for the relation to apply, one sentence each. Student-facing.",
"items": {
"type": "string"
},
"type": "array"
},
"fails_when": {
"description": "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.",
"items": {
"type": "string"
},
"type": "array"
},
"implications": {
"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.",
"items": {
"additionalProperties": false,
"properties": {
"form": {
"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.",
"enum": [
"direction",
"limit",
"scale",
"dominant_term",
"held_fixed",
"misuse"
],
"type": "string"
},
"statement": {
"description": "The implication as one student-facing sentence. 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).",
"minLength": 1,
"type": "string"
}
},
"required": [
"form",
"statement"
],
"type": "object"
},
"type": "array"
},
"name": {
"description": "The name students would use: the global alignment recurrence, the Henderson-Hasselbalch relation.",
"minLength": 1,
"type": "string"
},
"notes_private": {
"description": "Instructor-facing. Never rendered on a student page or exported where a student can see it.",
"type": "string"
},
"recall": {
"description": "Students are expected to know this relation from memory. Whether an exam may print it is course policy (`policy.exam_conditions.equations`).",
"type": "boolean"
},
"says": {
"description": "What the relation claims, in words, as a student should be able to state it with the symbols covered. Student-facing. 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).",
"minLength": 1,
"type": "string"
},
"source": {
"additionalProperties": false,
"description": "Where the course's own source states it.",
"properties": {
"locator": {
"description": "Where inside the work: §6.1, pp. 4-9, eq. 3.12.",
"type": "string"
},
"ref": {
"description": "Citation key into `references`.",
"minLength": 1,
"type": "string"
}
},
"required": [
"ref"
],
"type": "object"
},
"status": {
"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.",
"enum": [
"proposed",
"approved"
],
"type": "string"
},
"symbols": {
"description": "Every symbol in `tex`, in order of first appearance. The validator requires `term` or `meaning` on each.",
"items": {
"additionalProperties": false,
"properties": {
"meaning": {
"description": "What the symbol stands for, when it has no term.",
"type": "string"
},
"symbol": {
"description": "The symbol as it appears in `tex`.",
"minLength": 1,
"type": "string"
},
"term": {
"description": "Term id, when the quantity has a glossary entry; its definition and units come from there.",
"type": "string"
},
"units": {
"description": "Units, when the symbol has no term or the term gives none.",
"type": "string"
}
},
"required": [
"symbol"
],
"type": "object"
},
"type": "array"
},
"tags": {
"description": "Free-form tags.",
"items": {
"type": "string"
},
"type": "array"
},
"tex": {
"description": "The relation in LaTeX, without surrounding dollar signs. Rendered as display math.",
"minLength": 1,
"type": "string"
}
},
"required": [
"name",
"tex",
"says"
],
"type": "object"
},
"description": "Relations by id, `eq-...`. Defined once, conventionally in the objective file whose targets first need it.",
"propertyNames": {
"pattern": "^eq-[a-z0-9]+(-[a-z0-9]+)*$"
},
"type": "object"
},
"learning_objectives": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"assessed": {
"description": "Set false for an objective you teach but do not test; coverage reporting will stop flagging it as a gap. This exempts its targets too.",
"type": "boolean"
},
"description": {
"description": "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. 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).",
"type": "string"
},
"lectures": {
"description": "Lecture ids that cover this.",
"items": {
"type": "string"
},
"type": "array"
},
"level_ceiling": {
"description": "Cognitive level. 1 = Remember (recalling terms, facts, and definitions); 2 = Understand (explaining ideas in your own words); 3 = Apply (using a procedure in a new situation); 4 = Analyze (taking a situation apart and relating the pieces); 5 = Evaluate/Create (judging alternatives or building something new)",
"maximum": 5,
"minimum": 1,
"type": "integer"
},
"order": {
"description": "Position in teaching order, low first. Derived since 2.0 from the position of this objective in a lecture's `teaches` list; an authored value still wins, and `coursebank migrate order` removes them.",
"minimum": 1,
"type": "integer"
},
"prerequisites": {
"description": "Objective ids that must come first. Cycles are rejected.",
"items": {
"type": "string"
},
"type": "array"
},
"tags": {
"description": "Free-form tags.",
"items": {
"type": "string"
},
"type": "array"
},
"text": {
"description": "The objective as a student would read it. Start with a verb.",
"minLength": 1,
"type": "string"
},
"unit": {
"type": "string"
}
},
"required": [
"text"
],
"type": "object"
},
"description": "Keyed by objective id, conventionally one entry per file. Its `lectures` list is derived from each lecture's `teaches`, so leave it out unless you prefer to declare it here.",
"type": "object"
},
"learning_targets": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"assessed": {
"description": "Set false for something you teach but do not test. An unassessed objective exempts its targets regardless.",
"type": "boolean"
},
"authoring": {
"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": {
"description": "The most demanding fair item at the ceiling, in one sentence: the evidence for the ceiling.",
"type": "string"
},
"constraints": {
"description": "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'.",
"items": {
"type": "string"
},
"type": "array"
},
"examples": {
"description": "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.",
"items": {
"type": "string"
},
"type": "array"
},
"number_work": {
"description": "The arithmetic an item needs, the operation and roughly how long it takes. Omit when there is none.",
"type": "string"
},
"relation_form": {
"description": "When the target tests a relation without evaluating it, which form it uses.",
"enum": [
"direction",
"limit",
"scale",
"dominant_term",
"held_fixed",
"misuse"
],
"type": "string"
},
"supplied": {
"description": "What an item on this target hands the student: the data, the scheme, a value.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"equations": {
"description": "Equation ids this target turns on.",
"items": {
"type": "string"
},
"type": "array"
},
"explanation": {
"description": "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. 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).",
"type": "string"
},
"lectures": {
"description": "Lecture ids that cover this.",
"items": {
"type": "string"
},
"type": "array"
},
"level_ceiling": {
"description": "Cognitive level. 1 = Remember (recalling terms, facts, and definitions); 2 = Understand (explaining ideas in your own words); 3 = Apply (using a procedure in a new situation); 4 = Analyze (taking a situation apart and relating the pieces); 5 = Evaluate/Create (judging alternatives or building something new)",
"maximum": 5,
"minimum": 1,
"type": "integer"
},
"misconceptions": {
"description": "Misconception ids an item on this target is most likely to draw on. Distractors are built from them, and the lecture names them.",
"items": {
"type": "string"
},
"type": "array"
},
"objective": {
"description": "The objective this target belongs to. Required: a target with no objective would be measured and never reported.",
"type": "string"
},
"order": {
"description": "Ignored since 2.0. An objective's targets are a set of question templates, not steps in a sequence — they are not taught in order and an exam samples from them — so a position asserts an order that does not exist. Where one target depends on another, say so with `prerequisites`. `coursebank migrate order` removes this.",
"minimum": 1,
"type": "integer"
},
"prerequisites": {
"description": "Target or objective ids that must come first. Cycles are rejected.",
"items": {
"type": "string"
},
"type": "array"
},
"tags": {
"description": "Free-form tags.",
"items": {
"type": "string"
},
"type": "array"
},
"terms": {
"description": "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.",
"items": {
"type": "string"
},
"type": "array"
},
"text": {
"description": "The target as a student would read it. Start with a verb.",
"minLength": 1,
"type": "string"
},
"values": {
"description": "Value ids this target uses.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"text",
"objective"
],
"type": "object"
},
"description": "The targets of this file's objective, by id. A target with no `lectures` of its own inherits its objective's.",
"type": "object"
},
"misconceptions": {
"additionalProperties": {
"additionalProperties": false,
"description": "One named mistake. Slides name it, items build distractors from it, and reports group misses by it.",
"properties": {
"belief": {
"description": "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. 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).",
"minLength": 1,
"type": "string"
},
"correction": {
"description": "Why it fails and what is true instead, in one to three sentences. Student-facing. 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).",
"minLength": 1,
"type": "string"
},
"error_type": {
"description": "What kind of mistake it is, in the bank's terms. recall_confusion — confused with a neighboring fact; terminology_swap — swapped similar terms; misconception — specific wrong model; incomplete_understanding — partial grasp of the idea; overgeneralization — applied a rule outside its scope; plausible_irrelevant — true but not what was asked; dropped_step — skipped a step; reversed_relationship — reversed the direction; wrong_procedure — used the wrong procedure; sign_or_magnitude_error — sign or magnitude slip; ignores_interacting_condition — ignored an interacting condition; correct_but_incomplete — correct but not best; common_shortcut — took a familiar shortcut",
"enum": [
"recall_confusion",
"terminology_swap",
"misconception",
"incomplete_understanding",
"overgeneralization",
"plausible_irrelevant",
"dropped_step",
"reversed_relationship",
"wrong_procedure",
"sign_or_magnitude_error",
"ignores_interacting_condition",
"correct_but_incomplete",
"common_shortcut"
],
"type": "string"
},
"evidence": {
"description": "Where the misconception has been seen, strongest first.",
"items": {
"additionalProperties": false,
"properties": {
"detail": {
"description": "What was seen: 'Exam 2 Q23, 22% chose it.'",
"type": "string"
},
"kind": {
"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.",
"enum": [
"exam",
"homework",
"poll",
"instructor",
"literature",
"textbook",
"persona"
],
"type": "string"
},
"locator": {
"description": "Where in that work.",
"type": "string"
},
"ref": {
"description": "Citation key, for literature or textbook evidence.",
"type": "string"
}
},
"required": [
"kind"
],
"type": "object"
},
"type": "array"
},
"notes_private": {
"description": "Instructor-facing. Never rendered on a student page or exported where a student can see it.",
"type": "string"
},
"status": {
"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.",
"enum": [
"proposed",
"approved"
],
"type": "string"
},
"tags": {
"description": "Free-form tags.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"belief",
"correction"
],
"type": "object"
},
"description": "Named mistakes by id, `mis-...`. Defined once; targets list the ones their items draw on, and bank options may name the one they encode.",
"propertyNames": {
"pattern": "^mis-[a-z0-9]+(-[a-z0-9]+)*$"
},
"type": "object"
},
"schema_version": {
"description": "Declared in course.yaml; fragments inherit it.",
"type": [
"string",
"number"
]
},
"stimuli": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"asset": {
"description": "Path to an image.",
"type": "string"
},
"body": {
"description": "The stimulus text, in coursebank markup.",
"minLength": 1,
"type": "string"
},
"caption": {
"type": "string"
}
},
"required": [
"body"
],
"type": "object"
},
"description": "Shared passages, figures, or data that several items refer to.",
"type": "object"
},
"terms": {
"additionalProperties": {
"additionalProperties": false,
"description": "One term students meet in this course.",
"properties": {
"definition": {
"description": "One plain sentence, student-facing, that defines the term without using it. Rendered in the lecture page's glossary and the course glossary. 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).",
"minLength": 1,
"type": "string"
},
"exam_wording": {
"description": "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.",
"type": "string"
},
"kind": {
"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.",
"enum": [
"standard",
"renamed",
"coined"
],
"type": "string"
},
"notes_private": {
"description": "Instructor-facing. Never rendered on a student page or exported where a student can see it.",
"type": "string"
},
"status": {
"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.",
"enum": [
"proposed",
"approved"
],
"type": "string"
},
"symbol": {
"description": "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.",
"type": "string"
},
"tags": {
"description": "Free-form tags.",
"items": {
"type": "string"
},
"type": "array"
},
"term": {
"description": "The word or phrase as this course writes it, as a student reads it on the lecture page.",
"minLength": 1,
"type": "string"
},
"textbook": {
"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.",
"items": {
"additionalProperties": false,
"properties": {
"locator": {
"description": "Where that text uses it.",
"type": "string"
},
"ref": {
"description": "Citation key into `references`; omit for a plain-English equivalent.",
"type": "string"
},
"term": {
"description": "The name an assigned text uses.",
"minLength": 1,
"type": "string"
}
},
"required": [
"term"
],
"type": "object"
},
"type": "array"
},
"units": {
"description": "Units of the quantity the term names, if any.",
"type": "string"
},
"variants": {
"description": "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.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"term",
"definition"
],
"type": "object"
},
"description": "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.",
"propertyNames": {
"pattern": "^term-[a-z0-9]+(-[a-z0-9]+)*$"
},
"type": "object"
},
"values": {
"additionalProperties": {
"additionalProperties": false,
"description": "One number students are taught. The validator requires `value` or `range`.",
"properties": {
"conflicts": {
"description": "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.",
"items": {
"type": "string"
},
"type": "array"
},
"exact": {
"description": "The unrounded value, for explanations and solutions.",
"type": "number"
},
"name": {
"description": "The quantity, specifically: free energy per ten-fold concentration ratio at 37 °C.",
"minLength": 1,
"type": "string"
},
"notes_private": {
"description": "Instructor-facing. Never rendered on a student page or exported where a student can see it.",
"type": "string"
},
"range": {
"description": "Low and high, when the course teaches a range rather than one value.",
"items": {
"type": "number"
},
"maxItems": 2,
"minItems": 2,
"type": "array"
},
"recall": {
"description": "Students are expected to know it. An exam never prints it, and no option or neighbouring item may give it away.",
"type": "boolean"
},
"say": {
"description": "The wording every material uses for it: 'about 6 kJ/mol'. Prose that writes {val-...} renders this.",
"minLength": 1,
"type": "string"
},
"source": {
"additionalProperties": false,
"description": "Where the course's own source states it.",
"properties": {
"locator": {
"description": "Where inside the work: §6.1, pp. 4-9, eq. 3.12.",
"type": "string"
},
"ref": {
"description": "Citation key into `references`.",
"minLength": 1,
"type": "string"
}
},
"required": [
"ref"
],
"type": "object"
},
"status": {
"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.",
"enum": [
"proposed",
"approved"
],
"type": "string"
},
"tags": {
"description": "Free-form tags.",
"items": {
"type": "string"
},
"type": "array"
},
"term": {
"description": "Term id of the quantity, when it has a glossary entry.",
"type": "string"
},
"units": {
"description": "Units, as printed.",
"type": "string"
},
"value": {
"description": "The value as taught (rounded as students learn it).",
"type": "number"
}
},
"required": [
"name",
"say"
],
"type": "object"
},
"description": "Taught numbers by id, `val-...`. Defined once; every material states a value in its `say` wording.",
"propertyNames": {
"pattern": "^val-[a-z0-9]+(-[a-z0-9]+)*$"
},
"type": "object"
}
},
"required": [
"learning_objectives"
],
"title": "coursebank objective file",
"type": "object"
}