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>
This commit is contained in:
alexmandClaude committed 2026-11-16 11:55:18 -05:00
1 parent 15175f64fd
commit 51a2fd235f
47 files changed
+10568 -55

No files matched your search

@@ -0,0 +1,291 @@
{
"$id": "https://coursebank.dev/schema/assessment.schema.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"description": "A record of what was given, to whom, and when. This is the join between item banks and grading data, and it is the source of truth for reuse history — there is no separate ledger to drift out of step.",
"properties": {
"assessment": {
"additionalProperties": false,
"properties": {
"attempts": {
"description": "Canvas attempt limit; -1 for unlimited.",
"type": "integer"
},
"date": {
"description": "Administration date. Drives reuse cooldowns.",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string"
},
"id": {
"description": "Assessment id, e.g. exam-4. Used in administration ids.",
"minLength": 1,
"type": "string"
},
"instructions": {
"type": "string"
},
"kind": {
"description": "practice is excluded from calibration by default, since conditions differ too much to pool.",
"enum": [
"exam",
"quiz",
"homework",
"practice",
"final"
],
"type": "string"
},
"minutes_allowed": {
"exclusiveMinimum": 0.0,
"type": "number"
},
"notes": {
"type": "string"
},
"platform": {
"enum": [
"paper",
"canvas",
"other"
],
"type": "string"
},
"scoring_policy": {
"enum": [
"keep_highest",
"keep_latest"
],
"type": "string"
},
"shuffle": {
"type": "boolean"
},
"term": {
"description": "Defaults to the course term.",
"type": "string"
},
"title": {
"description": "Printed title.",
"minLength": 1,
"type": "string"
}
},
"required": [
"id",
"title"
],
"type": "object"
},
"blueprint": {
"additionalProperties": false,
"description": "The design the form was drawn to satisfy. Kept so the form can be checked against the intent afterward.",
"properties": {
"banks": {
"description": "Restrict the draw to these banks.",
"items": {
"type": "string"
},
"type": "array"
},
"bonus_counts": {
"additionalProperties": {
"minimum": 0,
"type": "integer"
},
"type": "object"
},
"cooldown_days": {
"description": "Avoid items used within this many days. Relaxed with a warning rather than failing the draw.",
"minimum": 0,
"type": "integer"
},
"lectures": {
"description": "Restrict the draw to these lectures.",
"items": {
"type": "string"
},
"type": "array"
},
"level_counts": {
"additionalProperties": {
"minimum": 0,
"type": "integer"
},
"description": "How many scored items at each level, keyed by level number.",
"type": "object"
},
"max_per_bank": {
"minimum": 1,
"type": "integer"
},
"objective_minimums": {
"additionalProperties": {
"minimum": 0,
"type": "integer"
},
"description": "Minimum items per objective. Placed before level quotas, because a coverage requirement is the constraint most likely to become unsatisfiable. A requirement is satisfied by items on any of that objective's targets, so this stays short: name the dozen objectives the exam is meant to cover, not the hundred targets it is built from.",
"type": "object"
},
"seed": {
"description": "Makes the draw reproducible.",
"minimum": 0,
"type": "integer"
},
"topics": {
"description": "Restrict the draw to these topics.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"forms": {
"description": "Alternate forms. Option order is derived from the seed rather than stored, so every export of a form agrees.",
"items": {
"additionalProperties": false,
"properties": {
"id": {
"description": "Form label, e.g. A.",
"minLength": 1,
"type": "string"
},
"seed": {
"minimum": 0,
"type": "integer"
},
"shuffle_items": {
"type": "boolean"
},
"shuffle_options": {
"type": "boolean"
}
},
"required": [
"id",
"seed"
],
"type": "object"
},
"type": "array"
},
"items": {
"description": "One entry per question, in number order.",
"items": {
"additionalProperties": false,
"properties": {
"bonus": {
"type": "boolean"
},
"credit_overrides": {
"additionalProperties": {
"maximum": 1.0,
"minimum": 0.0,
"type": "number"
},
"description": "Partial credit decided after the fact, by option letter. Recording it here keeps the rescoring decision with the administration it applies to.",
"type": "object"
},
"distractors": {
"description": "The option ids offered alongside the key. Resolved when the assessment is assembled and written out explicitly, so a later bank edit cannot change the paper. Empty means the whole pool.",
"items": {
"type": "string"
},
"type": "array"
},
"dropped": {
"description": "Thrown out after the exam. Always excluded from statistics; dropped_as says whether it stays in the score.",
"type": "boolean"
},
"dropped_as": {
"description": "How a dropped question was handled on the grading platform. removed, the default, takes it out of the numerator and the denominator. full_credit keeps it in both: use it when everyone was given the points, so reports agree with the platform's grade.",
"enum": [
"removed",
"full_credit"
],
"type": "string"
},
"dropped_before_printing": {
"description": "Pulled before the paper was printed, so it never held a position and later questions moved up. Leave unset for a question thrown out after the exam: setting it wrongly attributes responses to the wrong items.",
"type": "boolean"
},
"fingerprint": {
"description": "What the item looked like when given. Validation warns if the item has since changed.",
"type": "string"
},
"item": {
"description": "Item reference, `bank::item-id` or a bare item id.",
"minLength": 1,
"type": "string"
},
"key": {
"description": "The option ids keyed correct for this administration. One for a single_best_answer, chosen from the item's pool of defensible keys.",
"items": {
"type": "string"
},
"type": "array"
},
"learning_objectives": {
"description": "The older name for learning_targets.",
"items": {
"type": "string"
},
"type": "array"
},
"learning_targets": {
"description": "Targets as administered.",
"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"
},
"number": {
"description": "The question number as administered. This is the join key to Gradescope and Canvas exports, so it must not change after the fact.",
"minimum": 1,
"type": "integer"
},
"points": {
"minimum": 0.0,
"type": "number"
},
"stem_digest": {
"description": "The stem as given. Validation treats a change as an error, since it is no longer the same question.",
"type": "string"
},
"variant": {
"description": "Digest of the item as this administration showed it: stem, administered options, and which was keyed. The key statistics pool on.",
"type": "string"
},
"version": {
"minimum": 1,
"type": "integer"
}
},
"required": [
"number",
"item"
],
"type": "object"
},
"type": "array"
},
"schema_version": {
"type": [
"string",
"number"
]
}
},
"required": [
"assessment"
],
"title": "coursebank assessment record",
"type": "object"
}
+599
View File
@@ -0,0 +1,599 @@
{
"$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"
}
@@ -0,0 +1,358 @@
{
"$id": "https://coursebank.dev/schema/calibration.schema.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"description": "The pooled statistics, by item id. Kept out of the banks: a bank's diff should be a change of intent, not the output of a grading run. Committed — every number here is a cohort aggregate, and there is no field for a student.",
"properties": {
"items": {
"additionalProperties": {
"additionalProperties": false,
"description": "Written by `coursebank calibrate`, not by hand. Pooled across administrations.",
"properties": {
"administrations": {
"description": "Administration ids pooled here.",
"items": {
"type": "string"
},
"type": "array"
},
"discrimination_index": {
"maximum": 1.0,
"minimum": -1.0,
"type": "number"
},
"fingerprint": {
"description": "Hash of what a student saw. When it stops matching the item, these statistics describe a different question.",
"type": "string"
},
"flags": {
"items": {
"enum": [
"negative_discrimination",
"low_discrimination",
"distractor_outperforms_key",
"key_underperforms",
"too_easy",
"too_hard",
"high_rapid_guess",
"nonfunctioning_distractor",
"dif_flagged",
"ambiguous",
"design_mismatch"
],
"type": "string"
},
"type": "array"
},
"irt": {
"additionalProperties": false,
"properties": {
"a": {
"description": "Discrimination.",
"type": "number"
},
"b": {
"description": "Difficulty.",
"type": "number"
},
"bayesian": {
"description": "Whether priors were used. On a class-sized sample they should be.",
"type": "boolean"
},
"c": {
"description": "Lower asymptote, 3PL only.",
"maximum": 1.0,
"minimum": 0.0,
"type": "number"
},
"model": {
"enum": [
"rasch",
"2pl",
"3pl"
],
"type": "string"
},
"n": {
"minimum": 0,
"type": "integer"
},
"se_a": {
"minimum": 0.0,
"type": "number"
},
"se_b": {
"minimum": 0.0,
"type": "number"
}
},
"required": [
"a",
"b"
],
"type": "object"
},
"mean_response_time_seconds": {
"minimum": 0.0,
"type": "number"
},
"n_examinees": {
"minimum": 0,
"type": "integer"
},
"option_stats": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"lower_group_rate": {
"description": "Rate in the bottom 27%.",
"maximum": 1.0,
"minimum": 0.0,
"type": "number"
},
"point_biserial": {
"maximum": 1.0,
"minimum": -1.0,
"type": "number"
},
"selection_rate": {
"description": "How often chosen.",
"maximum": 1.0,
"minimum": 0.0,
"type": "number"
},
"upper_group_rate": {
"description": "Rate in the top 27%.",
"maximum": 1.0,
"minimum": 0.0,
"type": "number"
}
},
"type": "object"
},
"type": "object"
},
"options": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"appearances": {
"minimum": 0,
"type": "integer"
},
"mean_selection_rate": {
"description": "Mean of the within-variant rates. For reading, not for acting on: each rate is a share of a different set.",
"maximum": 1.0,
"minimum": 0.0,
"type": "number"
},
"n_examinees": {
"minimum": 0,
"type": "integer"
},
"never_chosen": {
"description": "Never chosen, anywhere. The claim that justifies retiring it.",
"type": "boolean"
}
},
"type": "object"
},
"description": "One record per option, pooled across every set it appeared in. Supports one claim — this option draws nobody, anywhere — which is what retires a distractor and what one administration cannot show.",
"type": "object"
},
"p_value": {
"description": "Observed proportion correct.",
"maximum": 1.0,
"minimum": 0.0,
"type": "number"
},
"point_biserial": {
"maximum": 1.0,
"minimum": -1.0,
"type": "number"
},
"rapid_guess_rate": {
"description": "Fraction answered faster than readable.",
"maximum": 1.0,
"minimum": 0.0,
"type": "number"
},
"updated": {
"description": "When calibration last ran.",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string"
},
"variants": {
"description": "One record per option set ever administered. A stem shown with different distractors is a different item, so a p-value pooled across both would average two questions.",
"items": {
"additionalProperties": false,
"properties": {
"administrations": {
"description": "The administrations pooled into these numbers.",
"items": {
"type": "string"
},
"type": "array"
},
"discrimination_index": {
"maximum": 1.0,
"minimum": -1.0,
"type": "number"
},
"distractors": {
"description": "The option ids offered alongside them.",
"items": {
"type": "string"
},
"type": "array"
},
"flags": {
"items": {
"enum": [
"negative_discrimination",
"low_discrimination",
"distractor_outperforms_key",
"key_underperforms",
"too_easy",
"too_hard",
"high_rapid_guess",
"nonfunctioning_distractor",
"dif_flagged",
"ambiguous",
"design_mismatch"
],
"type": "string"
},
"type": "array"
},
"irt": {
"additionalProperties": false,
"properties": {
"a": {
"description": "Discrimination.",
"type": "number"
},
"b": {
"description": "Difficulty.",
"type": "number"
},
"bayesian": {
"description": "Whether priors were used. On a class-sized sample they should be.",
"type": "boolean"
},
"c": {
"description": "Lower asymptote, 3PL only.",
"maximum": 1.0,
"minimum": 0.0,
"type": "number"
},
"model": {
"enum": [
"rasch",
"2pl",
"3pl"
],
"type": "string"
},
"n": {
"minimum": 0,
"type": "integer"
},
"se_a": {
"minimum": 0.0,
"type": "number"
},
"se_b": {
"minimum": 0.0,
"type": "number"
}
},
"required": [
"a",
"b"
],
"type": "object"
},
"key": {
"description": "The option ids keyed correct in this set.",
"items": {
"type": "string"
},
"type": "array"
},
"n_examinees": {
"minimum": 0,
"type": "integer"
},
"option_stats": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"lower_group_rate": {
"description": "Rate in the bottom 27%.",
"maximum": 1.0,
"minimum": 0.0,
"type": "number"
},
"point_biserial": {
"maximum": 1.0,
"minimum": -1.0,
"type": "number"
},
"selection_rate": {
"description": "How often chosen.",
"maximum": 1.0,
"minimum": 0.0,
"type": "number"
},
"upper_group_rate": {
"description": "Rate in the top 27%.",
"maximum": 1.0,
"minimum": 0.0,
"type": "number"
}
},
"type": "object"
},
"description": "Per-option behavior within this set, by option id.",
"type": "object"
},
"p_value": {
"description": "Proportion correct, for this option set only.",
"maximum": 1.0,
"minimum": 0.0,
"type": "number"
},
"point_biserial": {
"maximum": 1.0,
"minimum": -1.0,
"type": "number"
},
"variant": {
"description": "Digest of the stem, the administered options, and which was keyed.",
"type": "string"
}
},
"required": [
"variant"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
},
"description": "Keyed by item id, which since 2.0 names the item course-wide and carries no file name, so moving a question between banks does not orphan its statistics.",
"type": "object"
},
"schema_version": {
"type": [
"string",
"number"
]
}
},
"title": "coursebank calibration store",
"type": "object"
}
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,475 @@
{
"$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"
}
+175
View File
@@ -0,0 +1,175 @@
{
"$id": "https://coursebank.dev/schema/lecture.schema.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"description": "One session: its readings, and the objectives it develops. A fragment of the course file, merged on load.",
"properties": {
"lectures": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"date": {
"description": "Date delivered.",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string"
},
"description": {
"description": "The lecture in two to four sentences, student-facing: what it covers and the arc its objectives follow. The lecture page opens with it. 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).",
"type": "string"
},
"materials": {
"description": "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.",
"items": {
"additionalProperties": false,
"properties": {
"kind": {
"enum": [
"slides",
"brief",
"notes",
"notebook",
"recording",
"homework",
"other"
],
"type": "string"
},
"title": {
"description": "Link text. Defaults to the kind.",
"type": "string"
},
"url": {
"description": "Where it lives.",
"minLength": 1,
"type": "string"
}
},
"required": [
"kind",
"url"
],
"type": "object"
},
"type": "array"
},
"readings": {
"description": "Readings assigned with this lecture, in the order you assign them. A plain string is the pre-schema form and still loads.",
"items": {
"oneOf": [
{
"description": "The pre-schema form: a citation, unparsed.",
"type": "string"
},
{
"additionalProperties": false,
"properties": {
"focus": {
"description": "What to take from it. This is the sentence a student report quotes. 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"
},
"locator": {
"description": "Where inside the work: §6.1, pp. 212-219, ch. 3.",
"minLength": 1,
"type": "string"
},
"minutes": {
"description": "Estimated reading time, for the lecture page's workload line.",
"minimum": 1,
"type": "integer"
},
"path": {
"description": "Joined to the reference's base_url to reach this location.",
"type": "string"
},
"ref": {
"description": "Citation key into `references`.",
"minLength": 1,
"type": "string"
},
"role": {
"description": "supplemental means offered but not separately assessed.",
"enum": [
"assigned",
"supplemental"
],
"type": "string"
},
"skip": {
"description": "What to gloss, and why it is out of scope. 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"
},
"summary": {
"description": "What the section contains. 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"
},
"targets": {
"description": "Target ids this reading serves. A student who misses one of these is pointed here, so the list is what makes study guidance specific. Cite targets rather than objectives: a section of a book backs a specific performance, and a reading list resolved from an objective would send a student the same six sections whichever part of it they missed.",
"items": {
"type": "string"
},
"type": "array"
},
"text": {
"description": "A pre-schema citation string, held unparsed.",
"minLength": 1,
"type": "string"
},
"url": {
"description": "Full URL, when base_url does not cover the location.",
"type": "string"
}
},
"required": [
"ref"
],
"type": "object"
}
]
},
"type": "array"
},
"slides_url": {
"type": "string"
},
"teaches": {
"description": "The objectives this session develops. Each named objective gains this lecture in its `lectures` list when the course is loaded, so the pair is declared once, here, while planning the lecture.",
"items": {
"type": "string"
},
"type": "array"
},
"title": {
"description": "Lecture title.",
"minLength": 1,
"type": "string"
},
"unit": {
"description": "Unit id.",
"type": "string"
}
},
"required": [
"title"
],
"type": "object"
},
"description": "Keyed by lecture id, conventionally one entry per file.",
"type": "object"
},
"schema_version": {
"description": "Declared in course.yaml; fragments inherit it.",
"type": [
"string",
"number"
]
}
},
"required": [
"lectures"
],
"title": "coursebank lecture file",
"type": "object"
}
@@ -0,0 +1,213 @@
{
"$id": "https://coursebank.dev/schema/measurements.schema.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"description": "What one administration measured. Written once and not rewritten, like a seal: it records a thing that happened on a day. Cohort aggregates only — no per-section or per-student breakdown, because a small cell crossed with anything else stops being an aggregate.",
"properties": {
"administration": {
"additionalProperties": false,
"properties": {
"assessment": {
"type": "string"
},
"coursebank": {
"type": "string"
},
"date": {
"description": "When it was given.",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string"
},
"forms": {
"description": "The forms in play.",
"items": {
"type": "string"
},
"type": "array"
},
"generated": {
"description": "When the analysis was run.",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string"
},
"id": {
"type": "string"
},
"model": {
"type": "string"
},
"n_examinees": {
"description": "The number to read before any of the others: a point-biserial on twenty-seven students is a different kind of claim than one on three hundred.",
"minimum": 0,
"type": "integer"
},
"term": {
"type": "string"
}
},
"required": [
"id",
"assessment",
"n_examinees"
],
"type": "object"
},
"items": {
"items": {
"additionalProperties": false,
"properties": {
"discrimination_index": {
"maximum": 1.0,
"minimum": -1.0,
"type": "number"
},
"flags": {
"items": {
"enum": [
"negative_discrimination",
"low_discrimination",
"distractor_outperforms_key",
"key_underperforms",
"too_easy",
"too_hard",
"high_rapid_guess",
"nonfunctioning_distractor",
"dif_flagged",
"ambiguous",
"design_mismatch"
],
"type": "string"
},
"type": "array"
},
"irt": {
"additionalProperties": false,
"properties": {
"a": {
"description": "Discrimination.",
"type": "number"
},
"b": {
"description": "Difficulty.",
"type": "number"
},
"bayesian": {
"description": "Whether priors were used. On a class-sized sample they should be.",
"type": "boolean"
},
"c": {
"description": "Lower asymptote, 3PL only.",
"maximum": 1.0,
"minimum": 0.0,
"type": "number"
},
"model": {
"enum": [
"rasch",
"2pl",
"3pl"
],
"type": "string"
},
"n": {
"minimum": 0,
"type": "integer"
},
"se_a": {
"minimum": 0.0,
"type": "number"
},
"se_b": {
"minimum": 0.0,
"type": "number"
}
},
"required": [
"a",
"b"
],
"type": "object"
},
"item": {
"type": "string"
},
"n": {
"minimum": 0,
"type": "integer"
},
"number": {
"minimum": 1,
"type": "integer"
},
"option_stats": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"lower_group_rate": {
"description": "Rate in the bottom 27%.",
"maximum": 1.0,
"minimum": 0.0,
"type": "number"
},
"point_biserial": {
"maximum": 1.0,
"minimum": -1.0,
"type": "number"
},
"selection_rate": {
"description": "How often chosen.",
"maximum": 1.0,
"minimum": 0.0,
"type": "number"
},
"upper_group_rate": {
"description": "Rate in the top 27%.",
"maximum": 1.0,
"minimum": 0.0,
"type": "number"
}
},
"type": "object"
},
"type": "object"
},
"p_value": {
"description": "Proportion correct on this administration.",
"maximum": 1.0,
"minimum": 0.0,
"type": "number"
},
"point_biserial": {
"maximum": 1.0,
"minimum": -1.0,
"type": "number"
},
"stem_digest": {
"type": "string"
},
"variant": {
"type": "string"
}
},
"required": [
"item",
"number",
"n"
],
"type": "object"
},
"type": "array"
},
"schema_version": {
"type": [
"string",
"number"
]
}
},
"required": [
"administration"
],
"title": "coursebank administration record",
"type": "object"
}
@@ -0,0 +1,703 @@
{
"$id": "https://coursebank.dev/schema/objective.schema.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"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.",
"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"
},
"learning_objectives": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"assessed": {
"description": "Set false for an objective you teach but do not test; coverage reporting will stop flagging it as a gap. This exempts its targets too.",
"type": "boolean"
},
"description": {
"description": "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. 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).",
"type": "string"
},
"lectures": {
"description": "Lecture ids that cover this.",
"items": {
"type": "string"
},
"type": "array"
},
"level_ceiling": {
"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"
},
"order": {
"description": "Position in teaching order, low first. Derived since 2.0 from the position of this objective in a lecture's `teaches` list; an authored value still wins, and `coursebank migrate order` removes them.",
"minimum": 1,
"type": "integer"
},
"prerequisites": {
"description": "Objective ids that must come first. Cycles are rejected.",
"items": {
"type": "string"
},
"type": "array"
},
"tags": {
"description": "Free-form tags.",
"items": {
"type": "string"
},
"type": "array"
},
"text": {
"description": "The objective as a student would read it. Start with a verb.",
"minLength": 1,
"type": "string"
},
"unit": {
"type": "string"
}
},
"required": [
"text"
],
"type": "object"
},
"description": "Keyed by objective id, conventionally one entry per file. Its `lectures` list is derived from each lecture's `teaches`, so leave it out unless you prefer to declare it here.",
"type": "object"
},
"learning_targets": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"assessed": {
"description": "Set false for something you teach but do not test. An unassessed objective exempts its targets regardless.",
"type": "boolean"
},
"authoring": {
"additionalProperties": false,
"description": "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.",
"properties": {
"ceiling_item": {
"description": "The most demanding fair item at the ceiling, in one sentence: the evidence for the ceiling.",
"type": "string"
},
"constraints": {
"description": "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'.",
"items": {
"type": "string"
},
"type": "array"
},
"examples": {
"description": "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.",
"items": {
"type": "string"
},
"type": "array"
},
"number_work": {
"description": "The arithmetic an item needs, the operation and roughly how long it takes. Omit when there is none.",
"type": "string"
},
"relation_form": {
"description": "When the target tests a relation without evaluating it, which form it uses.",
"enum": [
"direction",
"limit",
"scale",
"dominant_term",
"held_fixed",
"misuse"
],
"type": "string"
},
"supplied": {
"description": "What an item on this target hands the student: the data, the scheme, a value.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"equations": {
"description": "Equation ids this target turns on.",
"items": {
"type": "string"
},
"type": "array"
},
"explanation": {
"description": "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. 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).",
"type": "string"
},
"lectures": {
"description": "Lecture ids that cover this.",
"items": {
"type": "string"
},
"type": "array"
},
"level_ceiling": {
"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"
},
"misconceptions": {
"description": "Misconception ids an item on this target is most likely to draw on. Distractors are built from them, and the lecture names them.",
"items": {
"type": "string"
},
"type": "array"
},
"objective": {
"description": "The objective this target belongs to. Required: a target with no objective would be measured and never reported.",
"type": "string"
},
"order": {
"description": "Ignored since 2.0. An objective's targets are a set of question templates, not steps in a sequence — they are not taught in order and an exam samples from them — so a position asserts an order that does not exist. Where one target depends on another, say so with `prerequisites`. `coursebank migrate order` removes this.",
"minimum": 1,
"type": "integer"
},
"prerequisites": {
"description": "Target or objective ids that must come first. Cycles are rejected.",
"items": {
"type": "string"
},
"type": "array"
},
"tags": {
"description": "Free-form tags.",
"items": {
"type": "string"
},
"type": "array"
},
"terms": {
"description": "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.",
"items": {
"type": "string"
},
"type": "array"
},
"text": {
"description": "The target as a student would read it. Start with a verb.",
"minLength": 1,
"type": "string"
},
"values": {
"description": "Value ids this target uses.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"text",
"objective"
],
"type": "object"
},
"description": "The targets of this file's objective, by id. A target with no `lectures` of its own inherits its objective's.",
"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"
]
},
"stimuli": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"asset": {
"description": "Path to an image.",
"type": "string"
},
"body": {
"description": "The stimulus text, in coursebank markup.",
"minLength": 1,
"type": "string"
},
"caption": {
"type": "string"
}
},
"required": [
"body"
],
"type": "object"
},
"description": "Shared passages, figures, or data that several items refer to.",
"type": "object"
},
"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"
}
},
"required": [
"learning_objectives"
],
"title": "coursebank objective file",
"type": "object"
}
@@ -0,0 +1,129 @@
{
"$id": "https://coursebank.dev/schema/references.schema.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"description": "The works the course cites, by citation key. One fragment of the course file; see course.schema.json for the whole.",
"properties": {
"references": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"arxiv": {
"description": "Bare arXiv id: 2301.00001.",
"type": "string"
},
"authors": {
"description": "Authors as `Family, Given`, in printed order.",
"items": {
"type": "string"
},
"type": "array"
},
"base_url": {
"description": "Prefix a reading's `path` is joined to, so the citation key appears once instead of once per reading.",
"type": "string"
},
"container": {
"description": "Journal, edited volume, or series.",
"type": "string"
},
"doi": {
"description": "Bare DOI: 10.1038/nature12373. For a manuscript this is usually the only link worth storing, since a reading list resolves it to doi.org.",
"pattern": "^(doi:|https?://(dx\\.)?doi\\.org/)?10\\.",
"type": "string"
},
"edition": {
"description": "Edition as printed: 7th.",
"type": "string"
},
"isbn": {
"type": "string"
},
"issue": {
"type": "string"
},
"kind": {
"description": "Kind of work, following BibTeX entry types.",
"enum": [
"book",
"chapter",
"article",
"preprint",
"thesis",
"website",
"software",
"dataset",
"video",
"other"
],
"type": "string"
},
"label": {
"description": "Short form a reading list shows, such as KKW. One work per label.",
"minLength": 1,
"type": "string"
},
"note": {
"description": "Access notes: reserve shelf, license.",
"type": "string"
},
"pages": {
"description": "Pages of the work, not of a reading.",
"type": "string"
},
"pmcid": {
"description": "PubMed Central id, which hosts the full text: PMC3084216.",
"type": "string"
},
"pmid": {
"description": "PubMed id, which hosts a record about the work: 21471563.",
"pattern": "^[0-9]+$",
"type": "string"
},
"publisher": {
"type": "string"
},
"role": {
"description": "required for a course text; supplemental for background.",
"enum": [
"required",
"supplemental"
],
"type": "string"
},
"title": {
"description": "Full title.",
"minLength": 1,
"type": "string"
},
"url": {
"description": "Canonical URL for the whole work.",
"type": "string"
},
"volume": {
"type": "string"
},
"year": {
"description": "Year of publication.",
"type": "integer"
}
},
"required": [
"title"
],
"type": "object"
},
"description": "Works by citation key.",
"type": "object"
},
"schema_version": {
"description": "Format version; currently 2.1. Declared in course.yaml; fragments inherit it.",
"type": [
"string",
"number"
]
}
},
"title": "coursebank references file",
"type": "object"
}