"""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"))))