Files
coursebank/docs/design/2.1/build_schemas.py
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

348 lines
22 KiB
Python

"""Build the coursebank 2.1 target schemas from the 2.0 originals.
Every change is additive: no field is renamed or removed, and no new field is required on an existing
object, so a 2.0 course validates unchanged. Run from this folder: python3 build_schemas.py
"""
import copy
import json
from pathlib import Path
HERE = Path(__file__).parent
SRC = HERE / "schemas-original"
OUT = HERE / "schemas"
OUT.mkdir(exist_ok=True)
def load(name):
return json.loads((SRC / name).read_text(encoding="utf-8"))
def dump(name, data):
(OUT / name).write_text(json.dumps(data, indent=2, sort_keys=True, ensure_ascii=False) + "\n", encoding="utf-8")
def s(desc=None, **kw):
d = {"type": "string"}
if desc:
d["description"] = desc
d.update(kw)
return d
def arr(items, desc=None):
d = {"type": "array", "items": items}
if desc:
d["description"] = desc
return d
def obj(props, required=None, desc=None):
d = {"type": "object", "additionalProperties": False, "properties": props}
if required:
d["required"] = required
if desc:
d["description"] = desc
return d
def idmap(prefix, entry, desc):
return {"type": "object", "description": desc,
"propertyNames": {"pattern": f"^{prefix}-[a-z0-9]+(-[a-z0-9]+)*$"},
"additionalProperties": entry}
BRACES = ("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).")
ID_LIST = {"type": "string"}
STATUS = {"type": "string", "enum": ["proposed", "approved"],
"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."}
TAGS = arr({"type": "string"}, "Free-form tags.")
PRIVATE = s("Instructor-facing. Never rendered on a student page or exported where a student can see it.")
CITE = obj({"ref": s("Citation key into `references`.", minLength=1),
"locator": s("Where inside the work: §6.1, pp. 4-9, eq. 3.12.")},
required=["ref"], desc="Where the course's own source states it.")
RELATION_FORMS = ["direction", "limit", "scale", "dominant_term", "held_fixed", "misuse"]
ERROR_TYPES = None # filled from the bank schema below
# ---------------------------------------------------------------- registry entries
TERM = obj({
"term": s("The word or phrase as this course writes it, as a student reads it on the lecture page.", minLength=1),
"definition": s("One plain sentence, student-facing, that defines the term without using it. Rendered in the lecture "
"page's glossary and the course glossary. " + BRACES, minLength=1),
"kind": {"type": "string", "enum": ["standard", "renamed", "coined"],
"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."},
"textbook": arr(obj({"term": s("The name an assigned text uses.", minLength=1),
"ref": s("Citation key into `references`; omit for a plain-English equivalent."),
"locator": s("Where that text uses it.")}, required=["term"]),
"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."),
"variants": arr({"type": "string"}, "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."),
"symbol": s("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."),
"units": s("Units of the quantity the term names, if any."),
"exam_wording": s("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."),
"status": STATUS, "tags": TAGS, "notes_private": PRIVATE,
}, required=["term", "definition"], desc="One term students meet in this course.")
EQUATION = obj({
"name": s("The name students would use: the global alignment recurrence, the Henderson-Hasselbalch relation.", minLength=1),
"tex": s("The relation in LaTeX, without surrounding dollar signs. Rendered as display math.", minLength=1),
"says": s("What the relation claims, in words, as a student should be able to state it with the symbols covered. "
"Student-facing. " + BRACES, minLength=1),
"symbols": arr(obj({"symbol": s("The symbol as it appears in `tex`.", minLength=1),
"term": s("Term id, when the quantity has a glossary entry; its definition and units come from there."),
"meaning": s("What the symbol stands for, when it has no term."),
"units": s("Units, when the symbol has no term or the term gives none.")},
required=["symbol"]),
"Every symbol in `tex`, in order of first appearance. The validator requires `term` or `meaning` on each."),
"implications": arr(obj({"form": {"type": "string", "enum": RELATION_FORMS,
"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."},
"statement": s("The implication as one student-facing sentence. " + BRACES, minLength=1)},
required=["form", "statement"]),
"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."),
"assumes": arr({"type": "string"}, "Conditions that must hold for the relation to apply, one sentence each. Student-facing."),
"fails_when": arr({"type": "string"}, "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."),
"recall": {"type": "boolean", "description": "Students are expected to know this relation from memory. Whether an exam "
"may print it is course policy (`policy.exam_conditions.equations`)."},
"source": CITE, "status": STATUS, "tags": TAGS, "notes_private": PRIVATE,
}, required=["name", "tex", "says"], desc="One relation students meet in this course.")
VALUE = obj({
"name": s("The quantity, specifically: free energy per ten-fold concentration ratio at 37 °C.", minLength=1),
"value": {"type": "number", "description": "The value as taught (rounded as students learn it)."},
"range": {"type": "array", "items": {"type": "number"}, "minItems": 2, "maxItems": 2,
"description": "Low and high, when the course teaches a range rather than one value."},
"units": s("Units, as printed."),
"say": s("The wording every material uses for it: 'about 6 kJ/mol'. Prose that writes {val-...} renders this.", minLength=1),
"exact": {"type": "number", "description": "The unrounded value, for explanations and solutions."},
"term": s("Term id of the quantity, when it has a glossary entry."),
"source": CITE,
"conflicts": arr({"type": "string"}, "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."),
"recall": {"type": "boolean", "description": "Students are expected to know it. An exam never prints it, and no option or "
"neighbouring item may give it away."},
"status": STATUS, "tags": TAGS, "notes_private": PRIVATE,
}, required=["name", "say"], desc="One number students are taught. The validator requires `value` or `range`.")
MISCONCEPTION = obj({
"belief": s("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. " + BRACES, minLength=1),
"correction": s("Why it fails and what is true instead, in one to three sentences. Student-facing. " + BRACES, minLength=1),
"error_type": None, # filled below
"evidence": arr(obj({"kind": {"type": "string",
"enum": ["exam", "homework", "poll", "instructor", "literature", "textbook", "persona"],
"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."},
"detail": s("What was seen: 'Exam 2 Q23, 22% chose it.'"),
"ref": s("Citation key, for literature or textbook evidence."),
"locator": s("Where in that work.")},
required=["kind"]),
"Where the misconception has been seen, strongest first."),
"status": STATUS, "tags": TAGS, "notes_private": PRIVATE,
}, required=["belief", "correction"], desc="One named mistake. Slides name it, items build distractors from it, and "
"reports group misses by it.")
REGISTRY_DESCS = {
"terms": "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.",
"equations": "Relations by id, `eq-...`. Defined once, conventionally in the objective file whose targets first need it.",
"values": "Taught numbers by id, `val-...`. Defined once; every material states a value in its `say` wording.",
"misconceptions": "Named mistakes by id, `mis-...`. Defined once; targets list the ones their items draw on, and bank "
"options may name the one they encode.",
}
def registries():
return {"terms": idmap("term", TERM, REGISTRY_DESCS["terms"]),
"equations": idmap("eq", EQUATION, REGISTRY_DESCS["equations"]),
"values": idmap("val", VALUE, REGISTRY_DESCS["values"]),
"misconceptions": idmap("mis", MISCONCEPTION, REGISTRY_DESCS["misconceptions"])}
# ---------------------------------------------------------------- additions to existing objects
OBJECTIVE_ADD = {
"description": s("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. " + BRACES),
}
TARGET_ADD = {
"explanation": s("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. " + BRACES),
"terms": arr(ID_LIST, "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."),
"equations": arr(ID_LIST, "Equation ids this target turns on."),
"values": arr(ID_LIST, "Value ids this target uses."),
"misconceptions": arr(ID_LIST, "Misconception ids an item on this target is most likely to draw on. Distractors are built "
"from them, and the lecture names them."),
"authoring": obj({
"ceiling_item": s("The most demanding fair item at the ceiling, in one sentence: the evidence for the ceiling."),
"supplied": arr({"type": "string"}, "What an item on this target hands the student: the data, the scheme, a value."),
"constraints": arr({"type": "string"}, "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'."),
"number_work": s("The arithmetic an item needs, the operation and roughly how long it takes. Omit when there is none."),
"relation_form": {"type": "string", "enum": RELATION_FORMS,
"description": "When the target tests a relation without evaluating it, which form it uses."},
"examples": arr({"type": "string"}, "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."),
}, desc="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."),
}
MATERIAL = obj({
"kind": {"type": "string", "enum": ["slides", "brief", "notes", "notebook", "recording", "homework", "other"]},
"title": s("Link text. Defaults to the kind."),
"url": s("Where it lives.", minLength=1),
}, required=["kind", "url"])
LECTURE_ADD = {
"description": s("The lecture in two to four sentences, student-facing: what it covers and the arc its objectives follow. "
"The lecture page opens with it. " + BRACES),
"materials": arr(MATERIAL, "Links the lecture page lists beside the readings: slides, the brief, notebooks, the recording. "
"`slides_url` is the older single-link form and still loads."),
}
READING_ADD = {
"minutes": {"type": "integer", "minimum": 1, "description": "Estimated reading time, for the lecture page's workload line."},
}
POLICY_ADD = {
"exam_conditions": obj({
"closed_book": {"type": "boolean"},
"calculator": {"type": "boolean", "description": "false: no item may need arithmetic beyond a few seconds, and "
"`target_text_forbid` usually bans words that promise a calculation."},
"equations": {"type": "string", "enum": ["never_printed", "sheet", "in_stem"],
"description": "Whether a relation an item turns on may appear: never (students bring the relation), "
"on a supplied sheet, or in the stem."},
"formats": arr({"type": "string", "enum": ["single_best_answer", "multiple_response", "true_false", "open_response"]},
"Item formats exams use now. Ceilings are still set by the most demanding fair item in any format."),
"seconds_per_item": {"type": "number", "exclusiveMinimum": 0.0, "description": "The time budget an item is written to."},
}, desc="How exams are sat, as students were told. Pipelines and the linter read these instead of assuming one course's rules."),
"blueprints": {"type": "object", "description": "Named default blueprints (module, final), as published to students. An "
"assessment's own `blueprint` wins.",
"additionalProperties": obj({
"level_counts": {"type": "object", "additionalProperties": {"type": "integer", "minimum": 0},
"description": "Scored items at each level, keyed by level number."},
"bonus_counts": {"type": "object", "additionalProperties": {"type": "integer", "minimum": 0}},
"minutes": {"type": "number", "exclusiveMinimum": 0.0}}, required=["level_counts"])},
"levels": {"type": "object", "description": "The course's own names and one-line descriptions for levels 1 to 5, as "
"students were told them. Lecture pages label ceilings with these; absent, "
"the generic Bloom names are used.",
"propertyNames": {"pattern": "^[1-5]$"},
"additionalProperties": obj({"name": s("Definitions, Concepts, Application ...", minLength=1),
"description": s("One line, as published.")}, required=["name"])},
"target_text_forbid": arr({"type": "string"}, "Regular expressions that must not match objective or target text, with "
"the reason in a comment beside them (for example '\\\\bcalculat' when "
"exams are calculator-free). The linter reports every match."),
}
def add_props(target, extra):
target["properties"].update(copy.deepcopy(extra))
# ---------------------------------------------------------------- bank (error_type enum shared with misconceptions)
bank = load("bank.schema.json")
opt = bank["properties"]["items"]["items"]["properties"]["options"]["items"]
ERROR_TYPES = copy.deepcopy(opt["properties"]["error_type"])
ERROR_TYPES["description"] = ERROR_TYPES["description"].replace(
"What kind of mistake this distractor is designed to catch.", "What kind of mistake it is, in the bank's terms.")
MISCONCEPTION["properties"]["error_type"] = ERROR_TYPES
opt["properties"]["misconception_id"] = {
"type": "string", "pattern": "^mis-[a-z0-9]+(-[a-z0-9]+)*$",
"description": "The registry misconception this distractor encodes. Reports group misses by it across items; the "
"option's own `misconception` text, when present, overrides the registry's wording for this item."}
opt["properties"]["misconception"]["description"] = (
"The specific wrong belief that leads here. This text is what student reports use, so write it as a completion of "
"'students pick this when ...'. Optional when `misconception_id` is set: the registry's `belief` is used.")
dump("bank.schema.json", bank)
# ---------------------------------------------------------------- objective fragment
objective = load("objective.schema.json")
add_props(objective["properties"]["learning_objectives"]["additionalProperties"], OBJECTIVE_ADD)
add_props(objective["properties"]["learning_targets"]["additionalProperties"], TARGET_ADD)
objective["properties"].update(registries())
objective["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.")
dump("objective.schema.json", objective)
# ---------------------------------------------------------------- lecture fragment
lecture = load("lecture.schema.json")
lec = lecture["properties"]["lectures"]["additionalProperties"]
add_props(lec, LECTURE_ADD)
reading_obj = lec["properties"]["readings"]["items"]["oneOf"][1]
add_props(reading_obj, READING_ADD)
for k in ("summary", "focus", "skip"):
reading_obj["properties"][k]["description"] += " " + BRACES
dump("lecture.schema.json", lecture)
# ---------------------------------------------------------------- course file
course = load("course.schema.json")
cp = course["properties"]
add_props(cp["learning_objectives"]["additionalProperties"], OBJECTIVE_ADD)
add_props(cp["learning_targets"]["additionalProperties"], TARGET_ADD)
add_props(cp["lectures"]["additionalProperties"], LECTURE_ADD)
c_reading = cp["lectures"]["additionalProperties"]["properties"]["readings"]["items"]["oneOf"][1]
add_props(c_reading, READING_ADD)
for k in ("summary", "focus", "skip"):
c_reading["properties"][k]["description"] += " " + BRACES
add_props(cp["policy"], POLICY_ADD)
cp.update(registries())
cp["schema_version"]["description"] = "Format version; currently 2.1."
course["description"] = ("Course identity, policy, and the registries that item and assessment files reference by id: "
"objectives, targets, lectures, references, stimuli, terms, equations, values, and misconceptions.")
dump("course.schema.json", course)
# ---------------------------------------------------------------- glossary fragment (new)
glossary = {
"$id": "https://coursebank.dev/schema/glossary.schema.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "coursebank glossary file",
"type": "object",
"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": dict(registries(), schema_version={"type": ["string", "number"],
"description": "Declared in course.yaml; fragments inherit it."}),
}
dump("glossary.schema.json", glossary)
# ---------------------------------------------------------------- unchanged, except the version line
references = load("references.schema.json")
references["properties"]["schema_version"]["description"] = "Format version; currently 2.1. Declared in course.yaml; fragments inherit it."
dump("references.schema.json", references)
for name in ("assessment.schema.json", "calibration.schema.json", "measurements.schema.json"):
dump(name, load(name))
print("wrote", ", ".join(sorted(p.name for p in OUT.glob("*.json"))))