{ "$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 ...'. Optional when `misconception_id` is set: the registry's `belief` is used.", "type": "string" }, "misconception_id": { "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.", "pattern": "^mis-[a-z0-9]+(-[a-z0-9]+)*$", "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" }