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>
595 lines
21 KiB
JSON
595 lines
21 KiB
JSON
{
|
|
"$id": "https://coursebank.dev/schema/bank.schema.json",
|
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
"additionalProperties": false,
|
|
"description": "A collection of items. Split banks by unit or topic; ids must be unique across the whole course, not just within a file.",
|
|
"properties": {
|
|
"bank": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"description": {
|
|
"type": "string"
|
|
},
|
|
"id": {
|
|
"description": "Bank id, unique within the course.",
|
|
"minLength": 1,
|
|
"type": "string"
|
|
},
|
|
"scope": {
|
|
"additionalProperties": false,
|
|
"description": "What this bank is meant to cover. Validation warns when an item strays outside it.",
|
|
"properties": {
|
|
"learning_targets": {
|
|
"description": "Target ids.",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"lectures": {
|
|
"description": "Lecture ids.",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"topics": {
|
|
"description": "Topics.",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"units": {
|
|
"description": "Unit ids.",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
}
|
|
},
|
|
"type": "object"
|
|
},
|
|
"title": {
|
|
"description": "Human-readable title.",
|
|
"minLength": 1,
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"id",
|
|
"title"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"defaults": {
|
|
"additionalProperties": false,
|
|
"description": "Applied to every item in the file that does not set the field. Saves repeating yourself; the item always wins.",
|
|
"properties": {
|
|
"author": {
|
|
"type": "string"
|
|
},
|
|
"lectures": {
|
|
"description": "Lecture ids for items with no sources of their own.",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"options_per_item": {
|
|
"minimum": 2,
|
|
"type": "integer"
|
|
},
|
|
"points": {
|
|
"exclusiveMinimum": 0.0,
|
|
"type": "number"
|
|
},
|
|
"topics": {
|
|
"description": "Topics added to every item.",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
}
|
|
},
|
|
"type": "object"
|
|
},
|
|
"items": {
|
|
"items": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"assets": {
|
|
"items": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"alt": {
|
|
"description": "Alt text. Required in practice: the linter flags an asset without it, because an exam question a screen reader cannot convey is not answerable.",
|
|
"type": "string"
|
|
},
|
|
"caption": {
|
|
"type": "string"
|
|
},
|
|
"path": {
|
|
"description": "Path to the image, relative to the course root.",
|
|
"minLength": 1,
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"path"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"author": {
|
|
"type": "string"
|
|
},
|
|
"bonus": {
|
|
"type": "boolean"
|
|
},
|
|
"cognitive_process": {
|
|
"description": "The specific cognitive operation. Must belong to the item's level — level 1: recognize, recall; level 2: interpret, exemplify, classify, summarize, infer, compare, explain; level 3: execute, implement; level 4: differentiate, organize, attribute; level 5: check, critique, generate, plan, produce.",
|
|
"enum": [
|
|
"recognize",
|
|
"recall",
|
|
"interpret",
|
|
"exemplify",
|
|
"classify",
|
|
"summarize",
|
|
"infer",
|
|
"compare",
|
|
"explain",
|
|
"execute",
|
|
"implement",
|
|
"differentiate",
|
|
"organize",
|
|
"attribute",
|
|
"check",
|
|
"critique",
|
|
"generate",
|
|
"plan",
|
|
"produce"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"design": {
|
|
"additionalProperties": false,
|
|
"description": "What you expected before giving the item. Kept separate from observed statistics so the two can be compared.",
|
|
"properties": {
|
|
"expected_difficulty": {
|
|
"description": "Fraction you expect to answer correctly.",
|
|
"maximum": 1.0,
|
|
"minimum": 0.0,
|
|
"type": "number"
|
|
},
|
|
"expected_discrimination": {
|
|
"enum": [
|
|
"low",
|
|
"moderate",
|
|
"high"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"expected_time_seconds": {
|
|
"exclusiveMinimum": 0.0,
|
|
"type": "number"
|
|
},
|
|
"rationale": {
|
|
"description": "Why this item exists and what it is meant to catch.",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"type": "object"
|
|
},
|
|
"format": {
|
|
"description": "single_best_answer keys exactly one option; multiple_response keys two or more; open_response takes no options and is graded from its solution.",
|
|
"enum": [
|
|
"single_best_answer",
|
|
"multiple_response",
|
|
"true_false",
|
|
"open_response"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"history": {
|
|
"description": "One entry per version. Versions must increase.",
|
|
"items": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"author": {
|
|
"type": "string"
|
|
},
|
|
"change": {
|
|
"description": "What changed and why.",
|
|
"minLength": 1,
|
|
"type": "string"
|
|
},
|
|
"date": {
|
|
"description": "When the change was made.",
|
|
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
|
|
"type": "string"
|
|
},
|
|
"version": {
|
|
"minimum": 1,
|
|
"type": "integer"
|
|
}
|
|
},
|
|
"required": [
|
|
"version",
|
|
"date",
|
|
"change"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"id": {
|
|
"description": "Item id, e.g. q-glycolysis-rate-limiting-step. Stable forever: assessment records and stored responses refer to it, so renaming one is a migration rather than an edit. A trailing counter is no longer expected — it recorded when the item was written, which git knows — but an id that still has one stays valid.",
|
|
"pattern": "^q-[a-z0-9]+(-[a-z0-9]+)*$",
|
|
"type": "string"
|
|
},
|
|
"learning_targets": {
|
|
"description": "Target ids this item measures. Reports aggregate these onto the target's objective, so an item with none contributes to nothing. Name the target rather than the objective: the objective follows from it, and recording which target was asked about is what lets a report explain a result instead of only stating it.",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"level": {
|
|
"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"
|
|
},
|
|
"notes_private": {
|
|
"description": "Never exported anywhere a student can see.",
|
|
"type": "string"
|
|
},
|
|
"options": {
|
|
"description": "Absent for an open_response item; at least two for any choice format.",
|
|
"items": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"correct": {
|
|
"type": "boolean"
|
|
},
|
|
"credit": {
|
|
"description": "Partial credit. Requires defensible: true and a defense.",
|
|
"maximum": 1.0,
|
|
"minimum": 0.0,
|
|
"type": "number"
|
|
},
|
|
"defense": {
|
|
"description": "The argument for that reading. Required when defensible is true.",
|
|
"type": "string"
|
|
},
|
|
"defensible": {
|
|
"description": "This option has a reading under which it is arguably correct. Required before granting partial credit.",
|
|
"type": "boolean"
|
|
},
|
|
"error_type": {
|
|
"description": "What kind of mistake this distractor is designed to catch. 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"
|
|
},
|
|
"explanation": {
|
|
"description": "Why this option is right or wrong. For you, not the student.",
|
|
"type": "string"
|
|
},
|
|
"feedback_student": {
|
|
"description": "Shown to a student who chose this, on Canvas and in reports.",
|
|
"type": "string"
|
|
},
|
|
"hint": {
|
|
"type": "string"
|
|
},
|
|
"id": {
|
|
"description": "Option id, unique within the item: `o-fourth-line`. An identity, not a print position — shuffled forms relabel on the way out. A single letter A-H is the pre-2.0 form; `coursebank migrate options` renames it.",
|
|
"pattern": "^(o-[a-z0-9]+(-[a-z0-9]+)*|[A-H])$",
|
|
"type": "string"
|
|
},
|
|
"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 ...'.",
|
|
"type": "string"
|
|
},
|
|
"retired": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"on": {
|
|
"description": "Retirement date.",
|
|
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
|
|
"type": "string"
|
|
},
|
|
"reason": {
|
|
"description": "Why it was retired.",
|
|
"minLength": 1,
|
|
"type": "string"
|
|
},
|
|
"replaced_by": {
|
|
"description": "Successor item id.",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"on",
|
|
"reason"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"selection_rate_expected": {
|
|
"description": "How often you expect this to be chosen. Compared against reality.",
|
|
"maximum": 1.0,
|
|
"minimum": 0.0,
|
|
"type": "number"
|
|
},
|
|
"text": {
|
|
"description": "The option as a student reads it.",
|
|
"minLength": 1,
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"id",
|
|
"text"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"maxItems": 8,
|
|
"minItems": 2,
|
|
"type": "array"
|
|
},
|
|
"points": {
|
|
"exclusiveMinimum": 0.0,
|
|
"type": "number"
|
|
},
|
|
"prerequisites": {
|
|
"description": "Objective ids a student needs before this item.",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"retired": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"on": {
|
|
"description": "Retirement date.",
|
|
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
|
|
"type": "string"
|
|
},
|
|
"reason": {
|
|
"description": "Why it was retired.",
|
|
"minLength": 1,
|
|
"type": "string"
|
|
},
|
|
"replaced_by": {
|
|
"description": "Successor item id.",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"on",
|
|
"reason"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"review": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"action": {
|
|
"enum": [
|
|
"keep",
|
|
"revise",
|
|
"award_partial_credit",
|
|
"correct_key",
|
|
"retire",
|
|
"monitor"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"notes": {
|
|
"type": "string"
|
|
},
|
|
"reviewed_by": {
|
|
"type": "string"
|
|
},
|
|
"reviewed_on": {
|
|
"description": "Review date.",
|
|
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"type": "object"
|
|
},
|
|
"solution": {
|
|
"additionalProperties": false,
|
|
"description": "The answer, the reasoning, and the rubric. Rendered in the solutions document and the answer key, never in a question paper.",
|
|
"properties": {
|
|
"accepted": {
|
|
"description": "Responses a short constructed answer is accepted as.",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"explanation": {
|
|
"description": "The worked reasoning a student learns from. The body of the solutions entry.",
|
|
"type": "string"
|
|
},
|
|
"model_answer": {
|
|
"description": "For an open-response item, the response a full-credit student writes; for a choice item, an optional one-line statement of the key.",
|
|
"type": "string"
|
|
},
|
|
"review": {
|
|
"description": "Where to look again after missing this item.",
|
|
"items": {
|
|
"oneOf": [
|
|
{
|
|
"description": "A citation, unparsed.",
|
|
"type": "string"
|
|
},
|
|
{
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"locator": {
|
|
"description": "Where inside the work: §6.1, pp. 4-9.",
|
|
"type": "string"
|
|
},
|
|
"path": {
|
|
"description": "Joined to the reference base_url.",
|
|
"type": "string"
|
|
},
|
|
"ref": {
|
|
"description": "Citation key into `references`.",
|
|
"minLength": 1,
|
|
"type": "string"
|
|
},
|
|
"text": {
|
|
"type": "string"
|
|
},
|
|
"url": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"type": "object"
|
|
}
|
|
]
|
|
},
|
|
"type": "array"
|
|
},
|
|
"rubric": {
|
|
"items": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"description": {
|
|
"description": "What earns the points on this line.",
|
|
"minLength": 1,
|
|
"type": "string"
|
|
},
|
|
"points": {
|
|
"minimum": 0.0,
|
|
"type": "number"
|
|
}
|
|
},
|
|
"required": [
|
|
"description"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"type": "array"
|
|
}
|
|
},
|
|
"type": "object"
|
|
},
|
|
"sources": {
|
|
"description": "Where the material was taught. Drives the 'review this' lines in student reports.",
|
|
"items": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"lecture": {
|
|
"description": "Lecture id from course.yaml.",
|
|
"minLength": 1,
|
|
"type": "string"
|
|
},
|
|
"readings": {
|
|
"description": "Specific readings.",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"recording_seconds": {
|
|
"minimum": 0,
|
|
"type": "integer"
|
|
},
|
|
"slides": {
|
|
"items": {
|
|
"minimum": 1,
|
|
"type": "integer"
|
|
},
|
|
"type": "array"
|
|
}
|
|
},
|
|
"required": [
|
|
"lecture"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"status": {
|
|
"description": "Only approved items can be drawn into an assessment.",
|
|
"enum": [
|
|
"draft",
|
|
"in_review",
|
|
"needs_revision",
|
|
"approved",
|
|
"retired"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"stem": {
|
|
"description": "The question. Ask something specific; the linter flags stems with no task in them.",
|
|
"minLength": 1,
|
|
"type": "string"
|
|
},
|
|
"stimulus": {
|
|
"description": "Stimulus id from course.yaml.",
|
|
"type": "string"
|
|
},
|
|
"title": {
|
|
"description": "Short internal label. Never shown to students.",
|
|
"type": "string"
|
|
},
|
|
"topics": {
|
|
"description": "Free-form topics, used for blueprint filtering.",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"version": {
|
|
"description": "Bump when you change what a student sees. Recorded on every administration so drift is detectable.",
|
|
"minimum": 1,
|
|
"type": "integer"
|
|
}
|
|
},
|
|
"required": [
|
|
"id",
|
|
"level",
|
|
"stem"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"schema_version": {
|
|
"type": [
|
|
"string",
|
|
"number"
|
|
]
|
|
}
|
|
},
|
|
"required": [
|
|
"bank",
|
|
"items"
|
|
],
|
|
"title": "coursebank item bank",
|
|
"type": "object"
|
|
}
|