Files
coursebank/docs/design/2.1/schemas/glossary.schema.json
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

476 lines
21 KiB
JSON

{
"$id": "https://coursebank.dev/schema/glossary.schema.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"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.",
"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"
},
"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"
]
},
"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"
}
},
"title": "coursebank glossary file",
"type": "object"
}