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,536 @@
{
"$id": "https://coursebank.dev/schema/course.schema.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"description": "Course identity, policy, and the registries that item and assessment files reference by id.",
"properties": {
"course": {
"additionalProperties": false,
"properties": {
"code": {
"description": "Course code, e.g. BIOSC 1540.",
"minLength": 1,
"type": "string"
},
"institution": {
"type": "string"
},
"instructors": {
"description": "Instructor names.",
"items": {
"type": "string"
},
"type": "array"
},
"slug": {
"description": "Short identifier used in file names and administration ids. Derived from the code if omitted.",
"type": "string"
},
"term": {
"description": "Term, e.g., 2026s.",
"minLength": 1,
"type": "string"
},
"title": {
"description": "Course title.",
"minLength": 1,
"type": "string"
}
},
"required": [
"code",
"title",
"term"
],
"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"
},
"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": "Learning objectives by id, conventionally `lo-...`. The tier a syllabus lists and a report classifies as met. Objectives only: the performances they are met by go in `learning_targets`.",
"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"
},
"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"
},
"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"
},
"text": {
"description": "The target as a student would read it. Start with a verb.",
"minLength": 1,
"type": "string"
}
},
"required": [
"text",
"objective"
],
"type": "object"
},
"description": "Learning targets by id. Each names the objective it belongs to. This is the tier items are tagged to and readings are cited against; results roll up to the objective. Ids must not start with `lo`, so that an id in an item or a report says which tier it belongs to without a lookup — `t-...` is the convention.",
"type": "object"
},
"lectures": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"date": {
"description": "Date delivered.",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string"
},
"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.",
"minLength": 1,
"type": "string"
},
"locator": {
"description": "Where inside the work: §6.1, pp. 212-219, ch. 3.",
"minLength": 1,
"type": "string"
},
"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.",
"minLength": 1,
"type": "string"
},
"summary": {
"description": "What the section contains.",
"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": "Lectures by id. Items cite these so reports can tell a student where to go back to.",
"type": "object"
},
"policy": {
"additionalProperties": false,
"description": "Course-wide defaults and rules that validation enforces.",
"properties": {
"allow_partial_credit": {
"description": "Whether any option may carry partial credit. When false, validation rejects items that do.",
"type": "boolean"
},
"bonus_levels": {
"description": "Levels a bonus item may be drawn from.",
"items": {
"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"
},
"type": "array"
},
"grade_scale": {
"description": "Letter-grade bands. Only the lower bound of each is recorded; a band runs up to the next one. Set this and a class report bins scores by letter rather than by ten-point interval.",
"items": {
"additionalProperties": false,
"properties": {
"attainment": {
"description": "The attainment word attached to the band.",
"type": "string"
},
"gpa": {
"description": "Grade points the band carries.",
"minimum": 0,
"type": "number"
},
"group": {
"description": "Color group for reports; defaults to the letter's first character.",
"type": "string"
},
"letter": {
"description": "The letter as it appears on a transcript.",
"type": "string"
},
"min": {
"description": "Lowest percentage earning this letter, inclusive.",
"maximum": 100,
"minimum": 0,
"type": "number"
}
},
"required": [
"letter",
"min"
],
"type": "object"
},
"type": "array"
},
"mastery_threshold": {
"description": "Rate at which an objective counts as met. 0.75 is a common choice.",
"maximum": 1.0,
"minimum": 0.0,
"type": "number"
},
"min_items_for_mastery": {
"description": "Below this many items on an objective, reports say 'not enough evidence' rather than classifying.",
"minimum": 1,
"type": "integer"
},
"options_per_item": {
"description": "Expected option count; the linter flags items that differ.",
"minimum": 2,
"type": "integer"
},
"partial_credit_floor_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"
},
"points_per_item": {
"description": "Default points for an item that does not set its own.",
"exclusiveMinimum": 0.0,
"type": "number"
}
},
"type": "object"
},
"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 the course cites, by citation key. Readings point in here, so an edition change is one edit.",
"type": "object"
},
"schema_version": {
"description": "Format version; currently 2.0.",
"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"
},
"units": {
"description": "Course units, in teaching order. That order drives report layout.",
"items": {
"additionalProperties": false,
"properties": {
"description": {
"type": "string"
},
"id": {
"description": "Unit id.",
"minLength": 1,
"type": "string"
},
"title": {
"description": "Unit title.",
"minLength": 1,
"type": "string"
}
},
"required": [
"id",
"title"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"course"
],
"title": "coursebank course file",
"type": "object"
}