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:
47 files changed
+10568
-55
No files matched your search
@@ -0,0 +1,56 @@
|
||||
# Prompt for a new Claude Code session in the coursebank repository
|
||||
|
||||
How to use it: copy this whole folder into the coursebank repository as `docs/design/2.1/` (or anywhere, and change the path below), open Claude Code at the repository root, and paste everything under the line. Claude Code stops once, after it has read the code and written a plan, and waits for your go-ahead.
|
||||
|
||||
---
|
||||
|
||||
You are working in the coursebank repository, the Rust tool that manages my course registry (course, lectures, objectives, targets, references, stimuli), item banks, assessments, measurements, and calibration. I want coursebank 2.1, and everything you need is in `docs/design/2.1/`:
|
||||
|
||||
- `SCHEMA-CHANGES.md`: the specification. What changes, why, the validation rules, the lints, the derived data, the rendering, the migration. Read it first and treat it as authoritative.
|
||||
- `schemas/`: the target JSON Schemas, one per file, written as coursebank would generate them. `schemas-original/` holds the 2.0 schemas they were built from, so `diff -r schemas-original schemas` shows every change.
|
||||
- `examples/v20/`: 2.0 fragments that must still validate unchanged. `examples/migration/`: a 1.0 `terms.yaml` and `values.yaml` and the `glossary.yaml` the migration should write. `examples/v21/`: a small course (course.yaml, references.yaml, glossary.yaml, two objective files, one lecture, one bank) that uses every new field and must validate with no errors.
|
||||
- `prototype/check21.py`: a Python sketch of every new error, lint, and lecture-page derivation. `python3 prototype/check21.py examples/v21 --selftest` breaks the example once per rule and shows each rule firing; that list is your test plan. `--page l09` prints the lecture-page content the renderer should produce, saved as `examples/v21/lecture-page-preview.md`.
|
||||
|
||||
## Why
|
||||
|
||||
Read `SCHEMA-CHANGES.md` "Why". In one paragraph: a lecture today is only its objectives, targets, and readings; its terms, numbers, equations, and common mistakes live in side files (`terms.yaml`, `values.yaml`) or in each pipeline's notes, so the lecture page shows students half of what they study from and the slide, brief, and item pipelines keep drifting copies. 2.1 makes those first-class registries, keyed by id and defined once, that targets point at; gives objectives, targets, and lectures short student-facing text; keeps the item-writing judgments the objectives prompt produces (the ceiling evidence, stem constraints, supplied data) on the target instead of losing them in chat; moves each course's exam conditions, blueprints, and level names into `policy` so the tools stop assuming one course; and lets a bank option name the misconception it encodes so reports can group misses by it.
|
||||
|
||||
## Ground rules
|
||||
|
||||
1. **Additive and backward compatible.** No field renamed or removed, no new required field on an existing object. Every course that validates under 2.0 validates under 2.1 with no new errors. `schema_version` becomes 2.1.
|
||||
2. **The schemas are generated; change the Rust.** Find how the JSON Schemas are produced (schemars or similar), change the types and their doc comments, and regenerate. The doc comments become the `description` strings, so carry the wording from `schemas/` over. Then diff the generated schemas against `docs/design/2.1/schemas/`: field names, types, enums, required lists, `additionalProperties: false`, and descriptions should match. Ordering and formatting do not matter. Where the generator cannot express something (the `propertyNames` id patterns are the likely case), enforce it in the validator and say so. List every remaining difference, with the reason, in your final report.
|
||||
3. **Ids are join keys.** Never rename an existing id or field. The new prefixes are `term-`, `eq-`, `val-`, `mis-`, and ids are unique across all registries.
|
||||
4. **Follow the repository's conventions** for module layout, error and lint codes, messages, tests, documentation, and the changelog. The prototype's codes (E2101 to E2108, W2101 to W2111, I2112, I2113) are placeholders: map each onto the repository's scheme and keep the mapping in `docs/design/2.1/CODES.md`.
|
||||
5. **Student-facing versus instructor-facing.** `authoring`, `notes_private`, `evidence`, `conflicts`, and `status` must never appear in a student page, a student report, or a student-visible export (Canvas, solutions). Add a test that renders the example and asserts none of their text is present.
|
||||
6. **Port semantics, not Python.** The prototype is a readable sketch. Where coursebank already has a better mechanism (its own loader, its own markup renderer, its own teaching order), use it and make the behaviour match the specification.
|
||||
|
||||
## Phase 0: read, then plan, then stop
|
||||
|
||||
Before changing anything, find out and write down in `docs/design/2.1/PLAN.md`:
|
||||
|
||||
- how the schemas are generated, and the command that regenerates them;
|
||||
- how fragments are discovered and merged (which directories and files the loader reads, and how a duplicate id is reported), and what it takes to load the new `glossary.yaml` fragment and the new registries from objective fragments;
|
||||
- where validation, lint, and rendering live, and how lint codes and error codes are numbered;
|
||||
- how teaching order is computed, and how the lecture page and student reports are rendered today (templates, markup handling of `{t-...}` braces and `$...$` math);
|
||||
- the test layout, and the fixtures that represent a real course;
|
||||
- any place where the specification conflicts with how the code works, with your proposed resolution;
|
||||
- the phases below, adjusted to what you found, each with the files it touches.
|
||||
|
||||
Then **stop and wait for me**. Do not start Phase 1 until I reply.
|
||||
|
||||
## Phases (after I approve the plan)
|
||||
|
||||
Work on a branch named `schema-2.1`. Commit at the end of each phase with a message that says what the phase did. Do not push, open a pull request, or merge unless I ask.
|
||||
|
||||
1. **Types and schemas.** The four registries and their entry types; the new fields on objectives, targets, lectures, readings, bank options, and policy; the glossary fragment type; the loader reading glossary entries from objective fragments, `glossary.yaml`, and `course.yaml`. Regenerate the schemas and diff them as in rule 2. Done when `examples/v20/` and `examples/v21/` both load, and the existing test suite passes.
|
||||
2. **Validation.** E2101 to E2108 as specified, including the extension of the duplicate-id rule across registries and the brace-reference resolution in every student-facing prose field. Done when the example validates with no errors and each error has a test built from the prototype's self-test case.
|
||||
3. **Lint.** W2101 to W2111, I2112, I2113. Done when `coursebank lint` on the example reports exactly W2101 for `val-per-decade` (migrated, not yet linked to a target) and I2113 (two proposed entries), and each lint has a test.
|
||||
4. **Derived data and rendering.** A glossary entry's first lecture; new versus earlier terms per lecture; the lecture page sections in the order the specification gives, with ceilings labelled by `policy.levels`; the course glossary page; brace references rendered as specified; student reports with the target explanation and the misconception correction, grouping misses by misconception. Done when a snapshot test of the example's lecture page has the content and order of `examples/v21/lecture-page-preview.md`, and the rule-5 test passes. Send me a screenshot or the rendered HTML of the example lecture page.
|
||||
5. **Migration.** `coursebank migrate glossary --terms terms.yaml --values values.yaml` writing `glossary.yaml`, with the report the specification describes (renamed ids; terms and values whose old `first` or `lectures` differ from the derived ones; entries no target lists yet). Done when migrating `examples/migration/terms.yaml` and `values.yaml` reproduces `examples/migration/glossary.expected.yaml` (field order aside) with the report its header comment describes, and migrating twice is a no-op. (`examples/v21/glossary.yaml` is that output after a person linked the value to its term.)
|
||||
6. **Documentation.** The authoring docs for the new registries and fields (with the example), the brace-reference table, the lint and error codes, the migration command, and the changelog entry for 2.1.
|
||||
|
||||
## Final report
|
||||
|
||||
When the phases are done, give me: what changed, by phase and file; the code mapping; every difference between the generated and the target schemas, with the reason; anything in the specification you could not do, or did differently, and why; how to run the migration on my course; and anything you think should change in the specification itself. Keep it short and put the details in `docs/design/2.1/REPORT.md`.
|
||||
|
||||
If anything in the specification is ambiguous in a way that changes behaviour, ask me rather than guess. If it is ambiguous only in a way that does not change behaviour, choose, and list the choice in the report.
|
||||
@@ -0,0 +1,124 @@
|
||||
# The lecture-spec pipeline: design
|
||||
|
||||
A sixth pipeline, upstream of the other five, that prepares, assesses, improves, audits, and proofreads the coursebank fragments that define a lecture and go on the course website: the lecture's description and materials, its objectives and targets (with explanations, ceilings, and item-writing notes), its readings, and the terms, equations, values, and misconceptions its targets need. It replaces the single objectives prompt with stages that each do one job in their own context, check each other blind, and stop for the instructor at the two decisions that matter.
|
||||
|
||||
This is the design for review. It is built after coursebank 2.1 validates the new format, so its mechanical gate is `coursebank validate` and `coursebank lint` rather than a second copy of those rules.
|
||||
|
||||
## What it produces
|
||||
|
||||
For one lecture (or a module, in audit mode):
|
||||
|
||||
- the fragments, as they will sit in the course repository: `lectures/l-<id>.yaml`, `objectives/lo-<id>.yaml` for every objective it creates or edits (objectives, targets, and the glossary entries their targets first need), and additions to `references.yaml` marked "verify before use";
|
||||
- the rendered lecture page, as students will see it;
|
||||
- `CHECK-ME.md`: what the instructor must verify by hand (proposed references, locators that could not be found in the supplied reading text, ceiling disputes decided by judgment, every assumption), each with its evidence;
|
||||
- a review packet: the blind readers' findings and what was done about each.
|
||||
|
||||
Everything comes back as files, in one zip, per the shared driver rules. Nothing is committed to the course repository unless the instructor asks.
|
||||
|
||||
## Where it sits
|
||||
|
||||
```
|
||||
material, readings, prior lectures
|
||||
│
|
||||
▼
|
||||
lecture-spec pipeline ──► coursebank fragments (the source of truth) ──► lecture page on the website
|
||||
│ │
|
||||
│ ├──► writing pipeline: the brief expands each target's explanation; terms, values from the registry
|
||||
│ ├──► lecture pipeline: targets, terms, equations, misconceptions (the first source for mistake boxes)
|
||||
│ └──► MCQ pipeline: ceilings, `authoring` notes, misconception ids for distractors
|
||||
▼
|
||||
CHECK-ME.md, review packet
|
||||
```
|
||||
|
||||
The three downstream pipelines stop reading `terms.yaml`, `values.yaml`, and their own misconception notes, and call `coursebank lint` for the checks those files fed.
|
||||
|
||||
## Modes
|
||||
|
||||
| mode | input | what runs | output |
|
||||
|---|---|---|---|
|
||||
| **build** | a lecture's material (slides, notes, outline, draft objectives, readings) | every stage | new fragments |
|
||||
| **revise** | an existing lecture's fragments, plus what changed and why | every stage, starting from the current fragments; ids kept | edits, shown as diffs |
|
||||
| **audit** | an existing lecture's fragments | intake, the mechanical gate, the blind readers, synthesis | findings only; nothing changed |
|
||||
| **proofread** | an existing lecture's fragments | the mechanical gate and the proofreader, on student-facing fields only | exact text edits |
|
||||
| **module** | every lecture in a module | the module auditor, after an audit of each lecture | module findings |
|
||||
| **link** | the migrated `glossary.yaml` | a one-time pass per lecture: list each migrated entry on the targets that need it, move it to its objective file | edits |
|
||||
|
||||
## Stages
|
||||
|
||||
The driver is the shared one (`orchestrator/SUBAGENTS.md`): one chat, a run-state file, sealed prompts for blind readers, files back as bundles. Models follow the shared role table.
|
||||
|
||||
| # | stage | who | model, effort | blind | writes |
|
||||
|---|---|---|---|---|---|
|
||||
| 0 | **Intake** | clerk | Sonnet, medium | | `sources/`: the registry slice (`coursebank course build`), the course policy, the earlier lectures' fragments, the material, each reading extracted to text with its headings kept, a files request for what is missing |
|
||||
| 1 | **Inventory** | clerk, one per material file when there are several | Sonnet, high | | `inventory.yaml`: every claim, case, term as used, equation, number, flagged mistake, and reading section in the material, each with a pointer to where it is. Later stages cite inventory entries, which is what makes "never fabricate" checkable |
|
||||
| 2 | **Objectives and targets** | author | Opus, high | | the objectives (top down, four to eight), the targets (three to eight each), ceilings with `authoring.ceiling_item`, `supplied`, `constraints`, `number_work`, `relation_form`, `examples`; prerequisites; the `teaches` order; the lecture `description`; a short read of the lecture and the scaffolding table |
|
||||
| | **Gate A** | instructor | | | approves the claims and ceilings. Everything after this hangs on them, so this is where a change is cheap |
|
||||
| 3 | **Glossary and explanations** | author, one per objective, in parallel | Opus, high | | each objective's `description`, each target's `explanation`, and the terms, equations, values, and misconceptions its targets list: reused by id when the registry has them, drafted as `status: proposed` when it does not |
|
||||
| 3j | **Join** | clerk | Sonnet, medium | | one set of fragments; two objectives proposing the same term, or one term defined twice in different words, go to the judge |
|
||||
| 4 | **Readings** | probe-cites, one per reference, in parallel | Sonnet, high | | each reading's `targets`, `summary`, `focus`, `skip`, `minutes`. A locator must be a heading or page found in the extracted reading; one that is not becomes a CHECK-ME line, never a guess |
|
||||
| 5 | **Mechanical gate** | driver | | | `coursebank validate`, `coursebank lint`, `speclint` (below). Errors go back to the stage that owns them, in the same subagent |
|
||||
| 6 | **Blind readers** | six, in one message | see below | yes | `review/responses/` |
|
||||
| 7 | **Synthesis** | judge | Opus, high | | `review/findings.md`, each finding routed to the stage that fixes it |
|
||||
| 8 | **Revise** | the authors of stages 2 to 4, continued | Opus, high | | the fixes; then stage 5 again, and the blind readers again on whatever changed |
|
||||
| 9 | **Proofread** | proofreader | Sonnet, high | | exact replacements in student-facing fields only: voice, register, the course's banned words and punctuation. A replacement that would change meaning is routed back instead of applied |
|
||||
| 10 | **Hand-off** | clerk | Sonnet, medium | | the fragments placed in the repository's working tree (not committed), the rendered lecture page, `CHECK-ME.md`, the bundle |
|
||||
| | **Gate B** | instructor | | | approves; `status: proposed` comes off what was approved |
|
||||
|
||||
### The blind readers (stage 6)
|
||||
|
||||
| reader | sees | asks | why |
|
||||
|---|---|---|---|
|
||||
| **item writer** (Sonnet, high; one per objective) | each target's text, explanation, and listed glossary entries, and the course's exam conditions; **not** the ceiling | write the most demanding fair item you can for this target, say its level, what the stem supplies, the arithmetic and the time it takes; then try one level higher and say why it fails | the objectives prompt asked the same model to set a ceiling and to justify it. A writer who does not know the ceiling either reaches it or does not: below means the ceiling is inflated or the text unclear, above means it is set too low. It also catches arithmetic the exam conditions rule out, and stems that need a constraint |
|
||||
| **student reading the target list** (Sonnet, high) | the rendered lecture page and the course guide's section on reading targets | for each target, write the question you think it promises and what you would practise; mark any word you could not look up | the guide tells students "a target is a question template with the options removed". If a student cannot name the question, the target fails the promise. Also catches a response format named in the text, and a term used before the page defines it |
|
||||
| **glossary novice** (Sonnet, high) | the terms, equations, values, and misconceptions only, in the order the page shows them | which definitions you could not follow, which used a word not yet defined, which symbol you could not place, which implication you could not see, which correction did not convince you | definitions and equation entries are what students study from; they are read cold here, the way a student meets them on the page |
|
||||
| **transfer probe** (Sonnet, medium) | each target's text only | write one case, not from any lecture, on which this target could be tested; say if you cannot | the prompt's rule "could a student meet this target on a case they have never seen" becomes a test. The synthesis compares the cases with the lecture's own examples in `inventory.yaml` |
|
||||
| **accuracy reviewer** (Opus, high; not blind) | everything, with the extracted readings and the material | is every definition, equation, implication, assumption, failure case, value, correction, summary, and reference true and supported by the sources; does each textbook name exist in the reading | a wrong definition or value is now rendered on the website and copied into slides, briefs, and items. One reviewer checks it before it spreads |
|
||||
| **leak check** (Sonnet, high; one per target with a level 3 or 4 ceiling) | the lecture page as a student sees it, then that target's `authoring.ceiling_item` | could you answer this item from the page alone, by finding the sentence | an explanation that states the answer to the hardest item on its own target turns a level 3 item into reading. The fix is in the explanation, not the item |
|
||||
|
||||
## `speclint`: the pipeline's own checks
|
||||
|
||||
What coursebank does not check, because it is a pipeline norm rather than a format rule. Each reads its numbers from the pipeline's course config, so a course can change them.
|
||||
|
||||
- **Counts.** Objectives per lecture (four to eight), targets per objective (three to eight), targets per lecture (a warning band the course sets; the objectives prompt's 30 to 45 and the guide's "twelve to forty" disagree, so this is one number per course, flagged both ways), two dense lectures in a row.
|
||||
- **Ceilings.** The leading verb of each target against the course's verb table; level spread per lecture and whether the module can supply the blueprint, bonus included; reportability (an objective that could not carry two items on one exam).
|
||||
- **Exam conditions.** When `policy.exam_conditions.calculator` is false: targets with `number_work` longer than the item budget, and the conceptual-to-numeric ratio in a lecture that carries an equation (at least two to one). A response format named in the text ("select", "in one sentence").
|
||||
- **Examples.** A proper noun from the inventory's examples appearing in target text, for the transfer probe and the synthesis to judge.
|
||||
- **Text.** Explanation length (two to four sentences), definitions of one sentence, the course's prose register (no em dashes, the banned vocabulary list), second person and verb first for objective and target text.
|
||||
- **Reuse.** A drafted target whose text is close to an existing one elsewhere in the registry: a revisit to register on the lecture, not a new id.
|
||||
- **Readings.** Every assessed target has an assigned reading or is flagged; every locator is found in the extracted reading; no `(ref, locator)` twice.
|
||||
- **Prerequisites.** Reach back four or more lectures with no revisit, for the lecture to re-activate deliberately.
|
||||
|
||||
## The shared modules (the prompt, rewritten)
|
||||
|
||||
The objectives prompt's content survives, split by the stage that needs it and corrected where it disagreed with the course or with itself.
|
||||
|
||||
| module | from the prompt | changed |
|
||||
|---|---|---|
|
||||
| `registry-format.md` | "The schema you must match" | the 2.1 format: glossary registries, explanations, `authoring`, brace references, where entries live |
|
||||
| `levels-and-ceilings.md` | the level scheme, the ladder, the verb table, the rules | course level names from `policy.levels`; the verb table is the guide's (define, state, name, identify / explain, compare, classify, interpret / predict or order given a change / several conditions / best explanation or a flaw), so targets, items, and the guide use one list |
|
||||
| `exam-conditions.md` | "closed-book, calculator-free, and all multiple choice" | read from `policy.exam_conditions` and `policy.blueprints`; the calculator rules apply only when the course says so |
|
||||
| `relations.md` | "six ways to test a relation" | the six forms are now the `implications` of an equation entry, and the source of level 2 and 3 targets on it; what each symbol means, what it assumes, where it fails |
|
||||
| `concepts-not-examples.md` | "concepts, not the examples that teach them" | examples drawn from several fields, not one; where each example goes is recorded in `authoring.examples` |
|
||||
| `format-independence.md` | the four rules and the constructed-response tag | unchanged in substance |
|
||||
| `glossary-writing.md` | new | how to write a definition, a term's kind and textbook names, an equation entry, a value's `say`, a misconception's belief and correction |
|
||||
| `readings.md` | the readings section and "never fabricate" | locators verified against the extracted text; `minutes` |
|
||||
| `house-style.md`, `prose-register.md` | house style, prose quality | the course voice from `course-context.md`; shared with the writing pipeline's register rules |
|
||||
| `course-contract.md` | new | the promises in *Learning to Learn* that a target list must keep: targets as question templates, ceilings as published, common mistakes as the source of distractors, numbers stated one way |
|
||||
|
||||
## What changes from the objectives prompt
|
||||
|
||||
1. **Course rules come from the course.** The prompt hard-codes one course's exam conditions, blueprint, density norms, and banned words. They now come from `policy` and the pipeline's course config, so the same pipeline serves every course.
|
||||
2. **One judgment per context.** The prompt asks one model to inventory, decide objectives, set ceilings, write readings, and grade itself, in one pass. The stages separate them, and the decision that matters most, the claims and their ceilings, gets its own context and the instructor's gate before anything else is built on it.
|
||||
3. **Ceilings are tested, not asserted.** The blind item writer replaces the prompt's self-written ceiling notes.
|
||||
4. **"Never fabricate" is checked.** Inventory pointers, locators matched against extracted readings, and an accuracy reviewer with the sources in front of it.
|
||||
5. **The judgments are kept.** The ceiling evidence, the stem constraints, the supplied data, and where each example went live in `authoring`, where the item writer and the slide drafter will find them, instead of in a chat transcript.
|
||||
6. **The lecture is fully specified.** Terms, equations, values, and misconceptions, each defined once, with the short canonical text students see on the page.
|
||||
7. **Student-facing text gets a proofread** by a reader who did not write it, limited to exact replacements so ids and meanings cannot drift.
|
||||
8. **The module is a mode,** not a suggestion at the end of the prompt.
|
||||
|
||||
## Decisions to make when it is built
|
||||
|
||||
- Whether the hand-off writes into the course repository's working tree (shown as a diff) or only returns the fragments in the bundle.
|
||||
- Which reading formats you can supply for locator checks (text exports, HTML, PDF), since a locator is verified against the extracted text.
|
||||
- The pipeline's course config: the density band, the verb table, the banned words and punctuation, the voice notes, per course.
|
||||
- Whether Gate A also shows the item writer's results (one more stop, but ceilings argued with evidence in hand) or only the drafted claims.
|
||||
@@ -0,0 +1,279 @@
|
||||
# coursebank 2.1: implementation plan
|
||||
|
||||
Phase 0 output. Written after reading `SCHEMA-CHANGES.md`, the prototype, the examples, and the code on branch
|
||||
`prelim-use` (clean, 412 unit + 20 integration + 4 doc tests passing). Nothing outside `docs/design/2.1/` has been
|
||||
changed. Section 7 has three questions whose answers change behaviour; everything else is a proposal I will follow
|
||||
unless you say otherwise.
|
||||
|
||||
## 1. How the schemas are produced
|
||||
|
||||
They are not generated from the Rust types. `src/authoring/jsonschema.rs` builds each schema by hand with
|
||||
`serde_json::json!`, one function per object (`course_schema`, `objective_schema`, `target_schema`, `lecture_schema`,
|
||||
`reading_mapping_schema`, `option_schema`, `policy_schema`, ...). The module doc says why: hand-written descriptions
|
||||
and enum lists are better tooltips than a derivation. There is no schemars, and the Rust doc comments are *not* the
|
||||
`description` strings.
|
||||
|
||||
- Regenerate: `coursebank schema` (writes `<course>/schema/*.schema.json` through `jsonschema::write_all`), or
|
||||
`pixi run cb schema -C <course>`.
|
||||
- `Kind` enumerates the eight files; `glossary.schema.json` needs a ninth, `Kind::Glossary`.
|
||||
- Baseline check: I generated today's schemas and compared them with `schemas-original/` as JSON values. Six match
|
||||
exactly. Two differ by one word each, already in the code before 2.1: `behaviour` (calibration, per-option
|
||||
history) and `Colour` (course, `grade_scale[].group`). `schemas-original/` has the American spellings, which no
|
||||
commit in this repository ever had. I will keep the code's spelling and list both as known differences.
|
||||
|
||||
**Effect on rule 2.** "Change the types and their doc comments, and regenerate" becomes: change the types (with doc
|
||||
comments in the repository's style), and port every edit in `build_schemas.py` into `jsonschema.rs` with the
|
||||
description strings copied word for word. Hand-written JSON can state `propertyNames` directly, so the id patterns go
|
||||
into the schema. The validator enforces them as well, because nothing checks the YAML against the JSON Schema at load
|
||||
time (serde only). An integration test compares each generated schema with `docs/design/2.1/schemas/` as a
|
||||
`serde_json::Value` (order-insensitive), with an explicit allow-list of known differences. I expect the list to hold
|
||||
only the two spellings above.
|
||||
|
||||
## 2. How fragments are discovered and merged
|
||||
|
||||
`src/model/course/fragment.rs`, entry point `CourseFile::load_dir` → `fragment::assemble(root)`:
|
||||
|
||||
- `files(layout)` lists, in order: `course.yaml` (always, role `Root`), `references.yaml` if present
|
||||
(`References`), sorted `lectures/*.yaml` (`Lecture`), sorted `objectives/*.yaml` (`Objective`). Banks are not
|
||||
fragments; `Catalog` loads them separately.
|
||||
- Each file is parsed into `Fragment` (`deny_unknown_fields`; every section optional). `Role::allows(section)`
|
||||
confines a role to its sections: an objective file may define objectives, targets, and stimuli; `course.yaml` may
|
||||
define anything.
|
||||
- `Merge::take` → `absorb` keeps `origins: BTreeMap<(Section, id), path>`. An id that a second file defines **in the
|
||||
same section** is reported by `duplicate()` (`"<noun> `id` is defined in two places: A and B. An id has one
|
||||
definition site..."`), and every merge problem comes back together in `Error::Invalid`.
|
||||
- Cross-section collisions are a validation problem, not a merge one: `CourseFile::problems` reports an id that is
|
||||
both an objective and a target.
|
||||
- `Merge::resolve` derives `objective.lectures` from `teaches`, `objective.order` from lecture order × `teaches`
|
||||
position, and a target's `lectures` from its objective's.
|
||||
|
||||
**What 2.1 needs:**
|
||||
|
||||
- `Section` gains `Terms`, `Equations`, `Values`, `Misconceptions`, which keeps origins and messages working.
|
||||
`Fragment`, `Merge`, and `CourseFile` gain the four maps.
|
||||
- A new `Role::Glossary` for `glossary.yaml` (loaded after `references.yaml`). It allows only the four registries.
|
||||
`Role::Objective` also allows them, and `Root` already allows everything.
|
||||
- `Layout::glossary_file()`.
|
||||
- Lecture files and `references.yaml` may **not** define registry entries. The spec says "any fragment may define
|
||||
glossary entries", but the target schemas add the registries only to `course`, `objective`, and `glossary`, and the
|
||||
prompt names exactly those three. I am following the schemas.
|
||||
- E2101 ("unique across all registries"): a duplicate in the same section is already caught by `absorb` and needs no
|
||||
change. A collision across sections becomes one check over the six registries (lo, t, term, eq, val, mis) in
|
||||
`problems()`, generalising the existing objective/target check. On 2.0 data it can only fire where 2.0 already
|
||||
fires.
|
||||
|
||||
## 3. Where validation, lint, and rendering live, and how codes work
|
||||
|
||||
**Validation (errors).** `CourseFile::validate` (`src/model/course.rs`: `problems`, `target_issues`,
|
||||
`reading_issues`, `prerequisite_cycles`), plus `BankFile::validate` → `validate_item` (`src/model/bank.rs`, which
|
||||
receives the course). `Catalog::validate` (`src/model/catalog.rs`) runs both, and `coursebank validate`
|
||||
(`src/commands/project.rs`) prints them. Messages are **plain strings with no codes**. `attribute()` prefixes each
|
||||
with the file that defined the first backticked id, so new messages must name their id first, in backticks.
|
||||
|
||||
**Lint (warnings).** `src/authoring/lint.rs`: `enum Rule`, `Rule::ALL`, `code()`, `severity()`
|
||||
(`catalog::Severity`: Low, Medium, High), `family()`, `description()`. Codes are **kebab-case and family-prefixed**:
|
||||
`cue-key-longest`, `complete-distractor-design`, `evidence-stale`. `lint_catalog` runs the per-item rules and three
|
||||
bank-wide ones. `coursebank lint` filters with `--only`, `--ignore`, and `--min-severity`, prints by subject, and
|
||||
exits non-zero on any finding unless `--no-fail` is passed.
|
||||
|
||||
**Code mapping (to go in `CODES.md`).** E-codes become validation messages with stable wording, matching the
|
||||
repository's uncoded errors. W and I codes become lint rules in a new `glossary` family:
|
||||
|
||||
| prototype | coursebank | severity (proposed) |
|
||||
|---|---|---|
|
||||
| E2101–E2108 | validation messages (no code); `CODES.md` gives each one's message stem and test | error |
|
||||
| W2101 | `glossary-unused` | low |
|
||||
| W2102 | `glossary-no-textbook-name` | medium |
|
||||
| W2103 | `glossary-no-exam-wording` | low |
|
||||
| W2104 | `glossary-circular-definition` | low |
|
||||
| W2105 | `glossary-coined-in-item` | medium |
|
||||
| W2106 | `glossary-value-unsourced` | low |
|
||||
| W2107 | `glossary-value-conflict` | medium |
|
||||
| W2108 | `glossary-forbidden-target-wording` | medium |
|
||||
| W2109 | `glossary-unlisted-term` | low |
|
||||
| W2110 | `glossary-recall-value-printed` | medium |
|
||||
| W2111 | `glossary-equation-no-implications` | low |
|
||||
| I2112 | `glossary-defined-elsewhere` | note (see Q3) |
|
||||
| I2113 | `glossary-proposed` | note (see Q3) |
|
||||
|
||||
**Rendering.** The lecture pages are `src/export/lecture.rs`: `objectives_markdown` and `readings_markdown`, in
|
||||
Quarto or Plain Markdown, run by `coursebank lecture objectives|readings <id>` (`src/commands/lectures.rs`). There is
|
||||
no combined lecture page and no glossary page today. Student reports have two renderers, both fed by
|
||||
`analysis/students.rs::missed_items` (`MissedItem.misconception` and `.feedback`, taken from the chosen option):
|
||||
Markdown in `src/export/report.rs::student_markdown`, and Typst through `src/export/typst/payload.rs` and
|
||||
`templates/student-report.typ`. Student-visible exports are `export/qti.rs` (Canvas), `export/site.rs` (encrypted
|
||||
solutions), `export/practice.rs`, and the Typst exam and key.
|
||||
|
||||
## 4. Teaching order, and how braces and math are handled today
|
||||
|
||||
- **Teaching order** is computed in `Merge::resolve`: lectures in **id order** (a `BTreeMap`, not by date), then
|
||||
each lecture's `teaches` position, which sets `objective.order`. `objectives_in_order` sorts by unit rank, then
|
||||
`order`, then id. `targets(objective)` sorts by effective ceiling, then id: the 2.0 rule the spec keeps. The
|
||||
prototype sorts lectures by `(date, id)` instead. The spec says "the existing one", so I will use coursebank's id
|
||||
order (the example has one lecture, so the two agree on it).
|
||||
- **A term's first lecture** will walk lectures in that order, the objectives in `teaches` order, and the targets in
|
||||
`targets()` order (ceiling, then id). The prototype walks targets in file order. For the example both give the
|
||||
preview's new-terms order.
|
||||
- **Braces.** `CourseFile::expand_objective_refs` replaces `{id}` only when `id` is a declared objective or target,
|
||||
so `$U_\text{final}$` passes through. `readings_markdown` renders such a reference as `T n`, the target's position
|
||||
on the page, or as the target's text when it is not on the page. Only reading `summary`, `focus`, and `skip` are
|
||||
expanded today. 2.1 generalises this into one `expand_refs` that resolves the six prefixes and takes a renderer
|
||||
callback, keeping 2.0 behaviour for unprefixed ids. E2106 scans only the prefixed forms the prototype's `BRACE`
|
||||
pattern matches, so `10^{59}` and `\text{final}` are never references.
|
||||
- **Math.** `util/markup.rs` has no regex engine. `to_typst` hands `$...$` to mitex; `to_html` and `to_markdown`
|
||||
leave `$` alone, and Quarto renders it. The lecture pages pass prose through to Quarto unconverted, and the new
|
||||
page will too: `$d$` symbols stay inline math, and `tex` is emitted as `$$...$$`.
|
||||
|
||||
## 5. Tests and fixtures
|
||||
|
||||
Unit tests sit inline in each module (`#[cfg(test)] mod tests`) and build courses in `std::env::temp_dir()` or
|
||||
directly from structs. `tests/docs.rs` checks Markdown fences and guide coverage. There is **no fixture representing
|
||||
a real course**; the README's biosc1000 and biosc1540 pictures are prose. Plan: `docs/design/2.1/examples/` becomes
|
||||
the fixture, read by new integration tests through `CARGO_MANIFEST_DIR`, so the examples and the tests cannot drift.
|
||||
|
||||
## 6. Where the specification conflicts with the code, and what I propose
|
||||
|
||||
1. **The schemas are hand-written, not generated** (section 1). Resolution as described there.
|
||||
2. **No numeric codes** (section 3). Resolution: the mapping table above, kept in `CODES.md`.
|
||||
3. **There is no regex engine** (`Cargo.toml` is deliberately small; `markup.rs` and `lint.rs` scan by hand). E2107,
|
||||
W2107, and W2108 need real regular expressions → **Q1**. W2104 and W2105 (whole-word, case-insensitive) reuse
|
||||
`lint.rs::contains_word` and need no regex.
|
||||
4. **E2106 on 2.0 fields vs. "no new errors on a 2.0 course".** A 2.0 reading whose `focus` contains `{t-typo}`
|
||||
validates today and renders the braces literally. Under E2106 as written it becomes an error → **Q2**.
|
||||
5. **Info-level findings.** `Severity` has no note level, and `coursebank lint` exits non-zero on any finding. If
|
||||
I2113 is an ordinary finding, every course with a proposed entry fails lint, which breaks pipelines that call
|
||||
`coursebank lint` → **Q3**.
|
||||
6. **The example bank does not load in coursebank 2.0.** `Item.status` is required in Rust (the JSON Schema does not
|
||||
require it, which is an older mismatch), and the example item has none. With `status: approved`, validation
|
||||
requires `cognitive_process`, `sources`, and `design`. Proposal: add `status: draft` to the example item, the
|
||||
smallest change that keeps it a valid bank, and record it in the report. (I checked: the two 2.0 fragments
|
||||
validate unchanged under today's binary.)
|
||||
7. **`docs/design/2.1/` breaks `tests/docs.rs`.** Two tests fail now that the folder is in place: every `.md` under
|
||||
`docs/` must be included in the guide, and the design docs have fences without a language. Proposal: have both
|
||||
tests skip `docs/design/`, since design records are not guide pages.
|
||||
8. **Existing lint rules and `misconception_id`.** `complete-distractor-design` fires when an option has neither
|
||||
`misconception` nor `error_type`, and `complete-student-feedback` uses only the option's own text. Proposal: an
|
||||
option with a `misconception_id` counts as designed and as having feedback (the registry's correction).
|
||||
9. **Report wording.** Today a report prints "The option you chose is the one students pick when
|
||||
{misconception}", because the option text is written as a completion. A registry `belief` is a full sentence in
|
||||
the student's voice. Proposal: the option's own `misconception` keeps today's sentence; registry-only options
|
||||
print "This answer reflects a common mistake: *belief*" followed by the correction. Misses sharing a
|
||||
`misconception_id` are grouped under one heading, with their question numbers listed.
|
||||
10. **"Reports exactly W2101 and I2113".** On the example, the existing per-item rules also fire: the bank item has
|
||||
no explanations or feedback on some distractors. I will read the Phase 3 criterion as covering the 2.1 rules
|
||||
(`coursebank lint --only <glossary codes>`) and show the full output in the report.
|
||||
11. **The preview's reading line** reads `(T t-align-fill-matrix)` because the prototype prints the raw id.
|
||||
coursebank renders `T 3` (the target's position on the page, as today). The snapshot test will expect `T 3`.
|
||||
12. **`policy.blueprints` and `policy.exam_conditions`** are stored and validated but read by no command, because
|
||||
no phase asks for it. `assemble --blueprint <name>` reading `policy.blueprints` would be a small follow-up.
|
||||
13. **Registry id prefixes** (`propertyNames`) are enforced by the validator as an extra error, since no runtime
|
||||
JSON Schema check exists. It sits next to E2101 in `CODES.md` as an addition. It cannot fire on 2.0 data, which
|
||||
has no registry entries.
|
||||
|
||||
## 7. Questions (behaviour changes; I will wait for answers)
|
||||
|
||||
**Q1. Regular expressions.** Add the `regex` crate (pure Rust, no unsafe in our code, with features trimmed to
|
||||
`std` plus the Unicode classes `\b`, `\s`, and case-insensitivity need)? The patterns in the examples (`5\.7\s*kJ`,
|
||||
`\bcomput`, `10\^\{?100\}?`) are valid in both Python's `re` and Rust's `regex`. Rust's `regex` has no
|
||||
look-around or backreferences, which `CODES.md` would document. The alternative is a small hand-written matcher in
|
||||
`util/`, which keeps the dependency list but means maintaining a regex engine. **I recommend adding `regex`.**
|
||||
|
||||
**Q2. E2106 on existing 2.0 fields.** (a) E2106 applies to every student-facing field, so a typo'd `{t-...}` in an
|
||||
old reading becomes an error. This is stricter, and arguably a bug fix, but it breaks rule 1 for such a course.
|
||||
(b) E2106 applies to the four new prefixes everywhere, and to `{lo-}`/`{t-}` only in the new 2.1 fields; an
|
||||
unresolved `{lo-}`/`{t-}` in a 2.0 reading field draws a lint warning instead and still renders as today.
|
||||
**I recommend (b)**, since it keeps rule 1 exact.
|
||||
|
||||
**Q3. Note-level findings.** Add `Severity::Note` below `Low` for `glossary-defined-elsewhere` and
|
||||
`glossary-proposed`, printed as `[note]`, shown by default, selectable with `--min-severity note`, and **not**
|
||||
making `lint` exit non-zero? Or treat them as `Low` findings that fail lint like any other? **I recommend `Note`**,
|
||||
so a course with proposed entries can still pass a pipeline's lint gate.
|
||||
|
||||
## 8. Phases and the files each touches
|
||||
|
||||
All work on a new branch `schema-2.1` (from `prelim-use`), one commit per phase, nothing pushed.
|
||||
|
||||
**Phase 1: types and schemas.**
|
||||
- `src/model/course/glossary.rs` (new, so `course.rs` does not grow past 3,000 lines): `Term`, `TextbookName`,
|
||||
`TermKind`, `Equation`, `Symbol`, `Implication`, `RelationForm`, `Value`, `Misconception`, `Evidence`,
|
||||
`EvidenceKind`, `EntryStatus`, `SourceRef`, `Authoring`, `Material`, `MaterialKind`.
|
||||
- `src/model/course.rs`: `SCHEMA_VERSION = "2.1"`; the four maps on `CourseFile`. New fields on `Objective`
|
||||
(`description`), `Target` (`explanation`, the four id lists, `authoring`), `Lecture` (`description`,
|
||||
`materials`), and `Reading` (`minutes`, through its hand-written `Serialize`/`Deserialize`). `Policy` gains
|
||||
`exam_conditions`, `blueprints`, `levels`, and `target_text_forbid`. Every new field is optional, with
|
||||
`skip_serializing_if`, so a 2.0 file round-trips unchanged.
|
||||
- `src/model/course/fragment.rs`, `src/model/layout.rs`: sections, `Role::Glossary`, `glossary.yaml`.
|
||||
- `src/model/item.rs`: `Choice.misconception_id`.
|
||||
- `src/authoring/jsonschema.rs`: `Kind::Glossary`, the new builders, the changed descriptions.
|
||||
- Struct literals across the crate (`CourseFile::skeleton`, test fixtures in `export/lecture.rs` and elsewhere)
|
||||
gain the new fields, or `..Default::default()` where the type allows it.
|
||||
- `tests/docs.rs`: skip `docs/design/` (conflict 7). `docs/design/2.1/examples/v21/banks/alignment.yaml`:
|
||||
`status: draft` (conflict 6).
|
||||
- `tests/schema_2_1.rs` (new): schemas equal the targets apart from the allow-list; `examples/v20` (in a temporary
|
||||
course with a minimal `course.yaml` and the references it cites) and `examples/v21` load and pass the 2.0
|
||||
validation; `examples/migration/glossary.expected.yaml` loads as a glossary fragment.
|
||||
- Done when both example sets load and the existing suite passes (`pixi run check`).
|
||||
|
||||
**Phase 2: validation.**
|
||||
- `src/model/course/glossary.rs`: the `glossary_issues` checks, E2102–E2107 and the id prefixes. `course.rs`:
|
||||
`problems()` calls them, and the cross-registry form of E2101.
|
||||
- The brace scanner, plus the student-facing prose walk (the prototype's `prose()`), in `course.rs` beside
|
||||
`expand_refs`.
|
||||
- `src/model/bank.rs::validate_item`: E2108.
|
||||
- Tests: one per error, each built from the prototype's self-test mutation of the example, plus a check that the
|
||||
example validates clean.
|
||||
|
||||
**Phase 3: lint.**
|
||||
- `src/authoring/lint.rs`: the 13 rules and a course-level `lint_course` called from `lint_catalog`.
|
||||
- If Q3 is yes: `src/model/catalog.rs` (`Severity::Note`), `src/cli.rs` (`SeverityArg`), and `lint` in
|
||||
`src/commands/project.rs`, which does not fail on notes. Every `match` on `Severity` (in `seal.rs`,
|
||||
`commands/handlers.rs`, and `commands/analysis.rs`) is updated.
|
||||
- Changes to existing rules from conflict 8.
|
||||
- Tests: one per rule, each from the self-test mutation, plus the example reporting exactly
|
||||
`glossary-unused` on `val-per-decade` and `glossary-proposed` (two entries) among the glossary rules.
|
||||
|
||||
**Phase 4: derived data and rendering.**
|
||||
- `course.rs`: `first_lecture(entry)`, and `lecture_glossary(lecture)` returning the lecture's new terms, earlier
|
||||
terms, equations, values, and misconceptions, in page order.
|
||||
- `export/lecture.rs`: `page_markdown` (sections in the spec's order, ceilings labelled from `policy.levels` and
|
||||
otherwise from the generic level names) and `glossary_markdown`. Brace rendering follows the spec's table. A
|
||||
`{term-}` links to the term's anchor on the page when the term is new there, and otherwise to the course glossary
|
||||
page (`glossary.html#term-...`, overridable with `--glossary-href`). `objectives_markdown` and `readings_markdown`
|
||||
keep their output, except that the new prefixes now expand in reading prose.
|
||||
- `src/cli.rs` and `commands/lectures.rs`: `coursebank lecture page <id>` and `coursebank lecture glossary`.
|
||||
- Reports: `analysis/students.rs` (`MissedItem` gains the target explanations, `misconception_id`, and the
|
||||
correction), `export/report.rs` (the new text, and grouping by misconception),
|
||||
`export/typst/payload.rs` and `templates/student-report.typ` (the same, for the PDF).
|
||||
- Tests: a snapshot of the example lecture page compared with `lecture-page-preview.md` for content and order
|
||||
(conflict 11 aside). The rule-5 test renders the lecture page, the glossary page, a Markdown and a Typst student
|
||||
report, and the Canvas, site, and practice exports of the example bank, and asserts that no `authoring`,
|
||||
`notes_private`, `evidence`, `conflicts`, or `status` text appears in any of them.
|
||||
- Deliverable: the example lecture page rendered to HTML with Quarto (installed here), sent to you as the HTML
|
||||
file and as a private artifact link.
|
||||
|
||||
**Phase 5: migration.**
|
||||
- `src/migrate.rs`: `glossary(root, terms, values, write)`, which parses the 1.0 list form leniently and reports
|
||||
unknown fields as dropped. It adds the id prefixes, maps `course`→`term` and `meaning`→`definition`, and drops
|
||||
`first` and `lectures`, comparing them with the derived first lecture or lecture set. It reports entries no target
|
||||
lists. It writes `glossary.yaml` and skips ids already defined anywhere in the course, so a second run is a no-op
|
||||
that reports "already present" and writes nothing.
|
||||
- When `glossary.yaml` already exists with other entries, new ones are inserted as text under the right key, in
|
||||
the module's line-oriented style, so hand edits and comments survive.
|
||||
- `src/cli.rs` (`MigrateCommand::Glossary { terms, values, dry_run }`) and `commands/project.rs`.
|
||||
- Tests: the expected output (as values, so field order does not matter), the report, and the second-run no-op.
|
||||
|
||||
**Phase 6: documentation.**
|
||||
- `docs/guide/glossary.md` (new, wired into `src/guide.rs`): the registries and new fields with the example, the
|
||||
brace-reference table, the error and lint codes, and the migration.
|
||||
- `docs/guide/setup.md` and `README.md` (the files table, "What validate checks, and what lint checks", "Migrating
|
||||
an older course" with schema version 2.1, the lecture outputs, the command reference). Module docs in `lib.rs`,
|
||||
`model.rs`, `fragment.rs`, and `authoring.rs` (its rule count is already stale: it says 26, and there are 30).
|
||||
- `CHANGELOG.md` (Unreleased, Added). `docs/design/2.1/CODES.md` and `REPORT.md`.
|
||||
|
||||
## 9. Notes for the report (not blocking)
|
||||
|
||||
- `say: 'about 10^{59}'` renders literally as `10^{59}`, because it is not inside `$...$`. The example probably
|
||||
wants `about $10^{59}$`. That is a content edit to the spec's example, which I will not make unless you ask.
|
||||
- `pyv` cannot run `prototype/check21.py` on this machine: the vendored PyYAML it points at
|
||||
(`pipelines/mcq-pipeline/tools/vendor`) is not there, because `pipelines/` holds only zip files. The Rust tests
|
||||
reproduce every self-test case, so the port does not depend on it.
|
||||
@@ -0,0 +1,16 @@
|
||||
# coursebank 2.1 and the lecture-spec pipeline
|
||||
|
||||
| file | what it is | who reads it |
|
||||
|---|---|---|
|
||||
| `CLAUDE-CODE-PROMPT.md` | the prompt for a new Claude Code session in the coursebank repository; copy this folder to `docs/design/2.1/` and paste the prompt | you, then Claude Code |
|
||||
| `SCHEMA-CHANGES.md` | the specification: what changes, why, the rules, the rendering, the migration | Claude Code (authoritative), you (to review) |
|
||||
| `schemas/` | the target 2.1 JSON Schemas (`glossary.schema.json` is new) | Claude Code |
|
||||
| `schemas-original/` | your 2.0 schemas, so `diff -r schemas-original schemas` shows every change | |
|
||||
| `build_schemas.py` | the script that produced `schemas/` from `schemas-original/`, every edit in one place | |
|
||||
| `examples/v20/` | 2.0 fragments that must still validate | tests |
|
||||
| `examples/v21/` | a small 2.1 course using every new field; `lecture-page-preview.md` is the page it should render | tests, and you, to see the format in use |
|
||||
| `examples/migration/` | a 1.0 `terms.yaml` and `values.yaml` and the `glossary.yaml` the migration should write | tests |
|
||||
| `prototype/check21.py` | an executable sketch of every new rule; `--selftest` breaks the example once per rule, `--page l09` prints the lecture page | Claude Code (to port), you (to try the rules) |
|
||||
| `PIPELINE-DESIGN.md` | the design of the lecture-spec pipeline, built once coursebank validates 2.1 | you |
|
||||
|
||||
Checked here: every schema is valid JSON Schema (2020-12); the 2.0 examples validate under both 2.0 and 2.1; the 2.1 examples and the migration's expected output validate under 2.1, merged and as fragments; the 2.1 fragments are rejected by 2.0; bad ids, bad enum values, unknown keys and missing required fields are rejected; all 19 prototype rules fire on their broken case; the example course has no errors.
|
||||
@@ -0,0 +1,187 @@
|
||||
# coursebank 2.1: what changes in the schemas, and why
|
||||
|
||||
This is the specification for coursebank 2.1. `schemas/` holds the target JSON Schemas; `examples/` holds course fragments that must validate (2.0 and 2.1); `prototype/check21.py` is an executable sketch of every new validation rule, lint, and lecture-page derivation, with a self-test that breaks the example once per rule. Where this document and the prototype disagree, this document wins.
|
||||
|
||||
## Why
|
||||
|
||||
A lecture today is specified by its objectives, its targets (each with a ceiling), and its readings. Everything else a lecture provides lives in files coursebank cannot see: the course's terms and numbers in `terms.yaml` and `values.yaml`, the named mistakes in each pipeline's notes, the equations nowhere at all. The lecture page therefore shows students half of what they need to study, and the slide, brief, and item pipelines each keep their own copy of the rest, which drifts.
|
||||
|
||||
The course guide (*Learning to Learn*) makes promises the 2.0 format cannot carry:
|
||||
|
||||
- **The target list is the study tool.** "The target list guides the lecture, readings, homework, and exam." A target says what to do; 2.1 adds the short canonical account of it (`explanation`) and the vocabulary, relations, numbers, and mistakes it turns on.
|
||||
- **Relations are understood, not computed.** "If you understand an equation well enough to say what each part does and why, you can answer these questions." An equation entry records what it says in words, what each symbol means, what it implies (direction, limit, scale, which term dominates, what is held fixed, how it is misused), what it assumes, and when it fails. The guide tells students that a level 4 question often asks which assumption failed; `assumes` and `fails_when` are where that comes from.
|
||||
- **Common mistakes become distractors.** "When I point out what students often get wrong in class and explain why, I'm showing you how I come up with wrong answers for tests." A misconception becomes a registry entry with an id: the lecture page lists it, slides name it, item options point at it, and reports can group misses by it across items.
|
||||
- **Numbers are stated one way.** The values file exists because the same number drifted across briefs, slides, and banks. 2.1 moves it into the registry, and prose can write `{val-...}` so every page renders the one approved wording.
|
||||
- **Several courses.** The objectives prompt hard-codes one course's exam conditions (closed book, no calculator, no printed equations, multiple choice, two minutes an item) and blueprint. 2.1 puts them in `policy`, so pipelines and lints read each course's own rules.
|
||||
|
||||
## Principles
|
||||
|
||||
1. **Additive.** No field is renamed or removed, and no new field is required on an existing object. Every 2.0 course validates unchanged (`examples/v20/`).
|
||||
2. **Defined once, by id.** Each new registry is a map keyed by id, like `learning_targets`, merged on load from any fragment. An id is defined in exactly one file, and ids are unique across all registries.
|
||||
3. **Targets point at the glossary; nothing points back.** A target lists the terms, equations, values, and misconceptions it needs. Which lecture introduces a term is derived (the first lecture, in teaching order, whose targets list it), the same way an objective's lectures are derived from `teaches`. There is no `introduced_in` to keep in sync.
|
||||
4. **Student-facing and instructor-facing fields are separate.** Every new prose field is marked as one or the other in its description. `authoring` and `notes_private` are never rendered on a student page or exported where a student can see them.
|
||||
5. **Short canonical text.** The registry holds a few sentences per objective and target, one-sentence definitions, and one-sentence statements about each equation. Long-form prose stays in the lecture brief, which is checked against the registry.
|
||||
|
||||
## New registries
|
||||
|
||||
Ids carry a prefix so any id in an item, a reading, a report, or a brace reference says which registry it belongs to without a lookup: `term-`, `eq-`, `val-`, `mis-` (alongside the existing `lo-`, `t-`, `q-`, `o-`). The schemas state the prefix as a `propertyNames` pattern; if the schema generator cannot express that, the validator enforces it.
|
||||
|
||||
### `terms:` (`term-...`)
|
||||
|
||||
| field | required | reader | what and why |
|
||||
|---|---|---|---|
|
||||
| `term` | yes | student | the word or phrase as the course writes it |
|
||||
| `definition` | yes | student | one plain sentence that does not use the term itself (lint W2104) |
|
||||
| `kind` | | both | `standard` (default), `renamed`, `coined`, carried over from `terms.yaml`: whether a student can look it up |
|
||||
| `textbook` | | student | the names the assigned texts use, `{term, ref, locator}`; a renamed or coined term without one draws W2102 |
|
||||
| `variants` | | tools | other surface forms, for matching in slides, briefs, and items |
|
||||
| `symbol`, `units` | | student | the notation and units when the term names a quantity; equations refer to the quantity by term id, so the symbol is written once |
|
||||
| `exam_wording` | | tools | coined terms only: what items write instead of the label (lint W2103, W2105) |
|
||||
| `status`, `tags`, `notes_private` | | | see "Status" below |
|
||||
|
||||
### `equations:` (`eq-...`)
|
||||
|
||||
| field | required | reader | what and why |
|
||||
|---|---|---|---|
|
||||
| `name` | yes | student | the name students would use |
|
||||
| `tex` | yes | student | LaTeX without dollar signs, rendered as display math |
|
||||
| `says` | yes | student | what the relation claims, in words, with the symbols covered |
|
||||
| `symbols` | | student | every symbol, in order, with a `term` id or a `meaning` (E2103), and `units` |
|
||||
| `implications` | | student | `{form, statement}`, form one of `direction`, `limit`, `scale`, `dominant_term`, `held_fixed`, `misuse`: the six things a question can ask about a relation without evaluating it, from the objectives prompt's "six ways to test a relation". They are the raw material for level 2 and 3 targets, and a ceiling-3 target that turns on an equation with none draws W2111 |
|
||||
| `assumes`, `fails_when` | | student | conditions for the relation, and where it breaks; the raw material for level 4 |
|
||||
| `recall` | | both | students are expected to know it; whether an exam prints it is `policy.exam_conditions.equations` |
|
||||
| `source` | | both | `{ref, locator}` |
|
||||
|
||||
### `values:` (`val-...`)
|
||||
|
||||
The fields of `values.yaml`, with two changes: `lectures` is gone (derived from the targets that list the value), and `term` links the quantity to its glossary entry.
|
||||
|
||||
| field | required | what and why |
|
||||
|---|---|---|
|
||||
| `name`, `say` | yes | the quantity, and the one wording every material uses; `{val-...}` in prose renders `say` |
|
||||
| `value` or `range` | one of them (E2104) | the number as taught, or `[low, high]` |
|
||||
| `units`, `exact`, `term`, `source` | | `exact` is the unrounded value for solutions; a value with no `source` draws W2106 |
|
||||
| `conflicts` | | regular expressions for variants that must not appear; must compile (E2107); a match in any student-facing prose or item text draws W2107 |
|
||||
| `recall` | | students must know it; an item that prints it draws W2110 |
|
||||
|
||||
### `misconceptions:` (`mis-...`)
|
||||
|
||||
| field | required | reader | what and why |
|
||||
|---|---|---|---|
|
||||
| `belief` | yes | student | the wrong idea as a student holds it; listed under common mistakes on the lecture page |
|
||||
| `correction` | yes | student | why it fails and what is true instead |
|
||||
| `error_type` | | tools | the bank's existing enum, so a registry entry and a distractor classify mistakes the same way |
|
||||
| `evidence` | | instructor | `{kind, detail, ref, locator}`, kind one of `exam`, `homework`, `poll`, `instructor`, `literature`, `textbook`, `persona`. `textbook` matters: when an assigned text states the misconception, the correction must name the framing it replaces |
|
||||
|
||||
### Status
|
||||
|
||||
Every new registry entry may carry `status: proposed | approved` (absent means approved). A pipeline that adds an entry marks it proposed; the instructor approves by deleting the line. Checks treat proposed entries exactly like approved ones, and the linter reports how many are waiting (I2113). This is the `terms.yaml` convention, kept.
|
||||
|
||||
## Where entries are defined
|
||||
|
||||
Any fragment may define glossary entries. The convention, reported but not enforced (I2112), is the objective file whose targets first need the entry. Cross-cutting entries, and everything migrated from `terms.yaml` and `values.yaml`, go in a new fragment, `glossary.yaml` (`schemas/glossary.schema.json`), until a pipeline or the instructor moves each one. `objective.schema.json` gains the four registries; `course.schema.json` gains them for the merged course.
|
||||
|
||||
## Changes to existing objects
|
||||
|
||||
| object | new field | reader | why |
|
||||
|---|---|---|---|
|
||||
| objective | `description` | student | two to four sentences under the objective on the lecture page: what it is about, why it matters, what it builds on or leads to. The guide asks students to read targets as a map; this is the legend |
|
||||
| target | `explanation` | student | the canonical account a student who has met the target could give, in two to four sentences. Not a worked example. The brief expands it; slides and items are checked against it |
|
||||
| target | `terms`, `equations`, `values`, `misconceptions` | tools | id lists; they drive the lecture page's glossary sections, the "new here" versus "from earlier" split, and the checks (E2102, W2101, W2109) |
|
||||
| target | `authoring` | instructor | `ceiling_item` (the most demanding fair item, the evidence for the ceiling), `supplied` (what the stem hands over), `constraints` (stem conditions that keep the item fair, which the validator cannot see), `number_work`, `relation_form`, `examples` (the named cases kept out of the target text). These are the per-target judgments the objectives prompt asks for and then loses in chat output; 2.1 keeps them where the item writer will look |
|
||||
| lecture | `description` | student | the lecture in two to four sentences; the lecture page opens with it |
|
||||
| lecture | `materials` | student | `{kind, title, url}` links (slides, brief, notes, notebook, recording, homework). `slides_url` still loads |
|
||||
| reading | `minutes` | student | estimated reading time, for a workload line on the page |
|
||||
| bank option | `misconception_id` | tools | the registry misconception the distractor encodes (E2108). The option's own `misconception` text, when present, overrides the registry's `belief` for that item; when absent, reports use the registry's |
|
||||
| policy | `exam_conditions` | tools | `closed_book`, `calculator`, `equations` (`never_printed`, `sheet`, `in_stem`), `formats`, `seconds_per_item` |
|
||||
| policy | `blueprints` | tools | named default blueprints (`module`, `final`), each `{level_counts, bonus_counts, minutes}`. An assessment's own blueprint still wins |
|
||||
| policy | `levels` | student | the course's names and one-line descriptions for levels 1 to 5, as students were told them; the lecture page labels ceilings with them |
|
||||
| policy | `target_text_forbid` | tools | regular expressions that must not match objective or target text (W2108); the objectives prompt's ban on "compute, calculate, estimate" becomes one course's setting |
|
||||
|
||||
Unchanged: `assessment`, `measurements`, `calibration`. `references` changes only its version line. `schema_version` is 2.1.
|
||||
|
||||
## Brace references
|
||||
|
||||
Any student-facing prose field may reference an entry in braces: `{term-...}`, `{eq-...}`, `{val-...}`, `{mis-...}`, `{t-...}`, `{lo-...}`. The 2.0 rule (a `{t-...}` in a reading's prose renders the target's number) extends to all of them:
|
||||
|
||||
| reference | renders as |
|
||||
|---|---|
|
||||
| `{term-...}` | the term's `term`, linked to its glossary entry |
|
||||
| `{eq-...}` | the equation's `name`, linked to its display block |
|
||||
| `{val-...}` | the value's `say` |
|
||||
| `{mis-...}` | the misconception's `belief`, quoted |
|
||||
| `{t-...}`, `{lo-...}` | the target's or objective's number (`T 4`, as today) |
|
||||
|
||||
Every reference must resolve (E2106). A target's `explanation` that names a term in braces should list that term in `terms` or inherit it through a prerequisite target (W2109).
|
||||
|
||||
## Rules
|
||||
|
||||
The codes below are the prototype's; map them onto coursebank's own code scheme and keep a table.
|
||||
|
||||
**Errors**
|
||||
|
||||
| code | rule |
|
||||
|---|---|
|
||||
| E2101 | an id is defined in two files, in any registry (the 2.0 rule, extended to the new registries; ids are unique across all of them) |
|
||||
| E2102 | a target's `terms`, `equations`, `values`, or `misconceptions` names an undeclared entry of that registry |
|
||||
| E2103 | an equation symbol names an undeclared term, or has neither `term` nor `meaning` |
|
||||
| E2104 | a value has neither `value` nor `range`, a `range` runs high to low, or its `term` is undeclared |
|
||||
| E2105 | a `ref` in a new registry (`source`, `textbook`, `evidence`) is not in `references` |
|
||||
| E2106 | a brace reference in student-facing prose does not resolve |
|
||||
| E2107 | a `conflicts` or `target_text_forbid` pattern does not compile |
|
||||
| E2108 | a bank option's `misconception_id` is undeclared |
|
||||
|
||||
**Lint**
|
||||
|
||||
| code | rule |
|
||||
|---|---|
|
||||
| W2101 | a glossary entry nothing needs: no target, equation symbol, value, or item option lists it |
|
||||
| W2102 | a renamed or coined term with no textbook name |
|
||||
| W2103 | a coined term with no `exam_wording` |
|
||||
| W2104 | a definition that uses the term it defines (or a variant) |
|
||||
| W2105 | a coined term (or variant) in an item's stem or option |
|
||||
| W2106 | a value with no `source` |
|
||||
| W2107 | a value's `conflicts` pattern matches student-facing prose or item text |
|
||||
| W2108 | objective or target text matches `policy.target_text_forbid` |
|
||||
| W2109 | a target's explanation names a term in braces that it neither lists nor inherits from a prerequisite target |
|
||||
| W2110 | an item's stem or option prints a `recall: true` value |
|
||||
| W2111 | a target with ceiling 3 or above turns on an equation that lists no `implications` |
|
||||
| I2112 | a glossary entry defined in an objective file other than the one whose targets first need it (a convention, reported as a note) |
|
||||
| I2113 | proposed entries waiting for approval, counted |
|
||||
|
||||
These replace checks that live in the pipelines today (the slide linter's W374 and W375, the bank linter's W334, W804, W805, the brief linter's terms and values checks), so all three pipelines can call `coursebank lint` instead of each reading `terms.yaml` and `values.yaml` itself.
|
||||
|
||||
## Derived data and rendering
|
||||
|
||||
**Teaching order** is the existing one: lectures in order, objectives in each lecture's `teaches` order.
|
||||
|
||||
**A glossary entry's first lecture** is the first lecture, in teaching order, with a target that lists it. A lecture's **new** terms are those whose first lecture it is; its **earlier** terms are the rest of what its targets list, each shown with the lecture that introduced it.
|
||||
|
||||
**The lecture page** shows, in order: the description; each objective with its description, its targets sorted by ceiling then id (the 2.0 rule) with each target's explanation and the ceiling labelled by `policy.levels`; new terms (with symbol, definition, and the textbook name for renamed and coined terms); earlier terms, linked; the equations its targets turn on (display, says, symbols, implications, assumes, fails when); the values (say, marked when students must know it); common mistakes (belief, correction); readings (with minutes); materials. `examples/v21/lecture-page-preview.md` shows the content and order the prototype derives for the example lecture; the layout is the renderer's.
|
||||
|
||||
**A course glossary page** lists every term alphabetically with its definition and its first lecture, and every equation and value with theirs.
|
||||
|
||||
**Student reports** gain two things: a missed item's target explanation (what meeting it looks like), and, when the chosen option has a `misconception_id`, the misconception's correction; misses that share a misconception across items are grouped under it.
|
||||
|
||||
**Never rendered for students:** `authoring`, `notes_private`, `evidence`, `conflicts`, `status`.
|
||||
|
||||
## Migration
|
||||
|
||||
`coursebank migrate glossary --terms terms.yaml --values values.yaml` writes `glossary.yaml`:
|
||||
|
||||
| from | to |
|
||||
|---|---|
|
||||
| `terms[].id: decade` | `terms: term-decade:` (prefix added; report the rename) |
|
||||
| `course`, `variants`, `kind`, `textbook`, `exam_wording`, `status` | the same fields (`course` becomes `term`) |
|
||||
| `meaning` | `definition` |
|
||||
| `first` | dropped: derived from targets. Report each term whose old `first` differs from the derived first lecture, and each term no target lists yet |
|
||||
| `values[].id: per-decade` | `values: val-per-decade:` |
|
||||
| `name`, `value`, `units`, `say`, `exact`, `source`, `conflicts`, `recall`, `status` | the same fields |
|
||||
| `lectures` | dropped: derived. Report differences the same way |
|
||||
|
||||
The migration leaves `terms.yaml` and `values.yaml` in place; the pipelines switch to the registry when it validates. Linking existing targets to the migrated entries is the new pipeline's job, not the migration's.
|
||||
|
||||
## Notes
|
||||
|
||||
- YAML 1.1 parsers (Python's PyYAML) read `1.0e59` as a string; the examples write `1.0e+59`, which both 1.1 and 1.2 parsers read as a number.
|
||||
- The schemas carry their documentation in `description` strings, which come from Rust doc comments. Keep the wording; it is what an author sees in an editor.
|
||||
@@ -0,0 +1,347 @@
|
||||
"""Build the coursebank 2.1 target schemas from the 2.0 originals.
|
||||
|
||||
Every change is additive: no field is renamed or removed, and no new field is required on an existing
|
||||
object, so a 2.0 course validates unchanged. Run from this folder: python3 build_schemas.py
|
||||
"""
|
||||
import copy
|
||||
import json
|
||||
from pathlib import Path
|
||||
|
||||
HERE = Path(__file__).parent
|
||||
SRC = HERE / "schemas-original"
|
||||
OUT = HERE / "schemas"
|
||||
OUT.mkdir(exist_ok=True)
|
||||
|
||||
|
||||
def load(name):
|
||||
return json.loads((SRC / name).read_text(encoding="utf-8"))
|
||||
|
||||
|
||||
def dump(name, data):
|
||||
(OUT / name).write_text(json.dumps(data, indent=2, sort_keys=True, ensure_ascii=False) + "\n", encoding="utf-8")
|
||||
|
||||
|
||||
def s(desc=None, **kw):
|
||||
d = {"type": "string"}
|
||||
if desc:
|
||||
d["description"] = desc
|
||||
d.update(kw)
|
||||
return d
|
||||
|
||||
|
||||
def arr(items, desc=None):
|
||||
d = {"type": "array", "items": items}
|
||||
if desc:
|
||||
d["description"] = desc
|
||||
return d
|
||||
|
||||
|
||||
def obj(props, required=None, desc=None):
|
||||
d = {"type": "object", "additionalProperties": False, "properties": props}
|
||||
if required:
|
||||
d["required"] = required
|
||||
if desc:
|
||||
d["description"] = desc
|
||||
return d
|
||||
|
||||
|
||||
def idmap(prefix, entry, desc):
|
||||
return {"type": "object", "description": desc,
|
||||
"propertyNames": {"pattern": f"^{prefix}-[a-z0-9]+(-[a-z0-9]+)*$"},
|
||||
"additionalProperties": entry}
|
||||
|
||||
|
||||
BRACES = ("May reference other entries in braces, {term-...}, {eq-...}, {val-...}, {mis-...}, {t-...} or {lo-...}; "
|
||||
"the validator checks each resolves and the renderer replaces it (a term with its linked name, an equation "
|
||||
"inline, a value with its `say`, a target with its number).")
|
||||
|
||||
ID_LIST = {"type": "string"}
|
||||
|
||||
STATUS = {"type": "string", "enum": ["proposed", "approved"],
|
||||
"description": "proposed marks an entry a pipeline or a collaborator added for the instructor to approve; "
|
||||
"approve it by deleting the field or setting approved. Checks treat proposed entries like "
|
||||
"approved ones, so a new entry is checked from the day it is written. Absent means approved."}
|
||||
|
||||
TAGS = arr({"type": "string"}, "Free-form tags.")
|
||||
PRIVATE = s("Instructor-facing. Never rendered on a student page or exported where a student can see it.")
|
||||
|
||||
CITE = obj({"ref": s("Citation key into `references`.", minLength=1),
|
||||
"locator": s("Where inside the work: §6.1, pp. 4-9, eq. 3.12.")},
|
||||
required=["ref"], desc="Where the course's own source states it.")
|
||||
|
||||
RELATION_FORMS = ["direction", "limit", "scale", "dominant_term", "held_fixed", "misuse"]
|
||||
|
||||
ERROR_TYPES = None # filled from the bank schema below
|
||||
|
||||
# ---------------------------------------------------------------- registry entries
|
||||
|
||||
TERM = obj({
|
||||
"term": s("The word or phrase as this course writes it, as a student reads it on the lecture page.", minLength=1),
|
||||
"definition": s("One plain sentence, student-facing, that defines the term without using it. Rendered in the lecture "
|
||||
"page's glossary and the course glossary. " + BRACES, minLength=1),
|
||||
"kind": {"type": "string", "enum": ["standard", "renamed", "coined"],
|
||||
"description": "standard: the textbooks use this name for this idea (the default). renamed: a standard idea "
|
||||
"under the course's own name or notation; students can look it up only if told the textbook "
|
||||
"name. coined: a label or metaphor the course invented; no textbook uses it."},
|
||||
"textbook": arr(obj({"term": s("The name an assigned text uses.", minLength=1),
|
||||
"ref": s("Citation key into `references`; omit for a plain-English equivalent."),
|
||||
"locator": s("Where that text uses it.")}, required=["term"]),
|
||||
"What the assigned texts call it, the first-listed text first. The linter flags a renamed or coined "
|
||||
"term without one, since a student needs a name a search will find."),
|
||||
"variants": arr({"type": "string"}, "Other surface forms that count as a use of the term: plurals, abbreviations. "
|
||||
"Matching is case-insensitive and whole-word on `term` and every variant."),
|
||||
"symbol": s("The notation, when the term names a quantity, in coursebank markup: $K_M$. Equations refer to the "
|
||||
"quantity by term id, so the symbol is written once, here."),
|
||||
"units": s("Units of the quantity the term names, if any."),
|
||||
"exam_wording": s("Coined terms only: the plain wording items write instead of the label. A coined label is a "
|
||||
"teaching aid, not tested vocabulary, so the linter flags it in an item stem or option."),
|
||||
"status": STATUS, "tags": TAGS, "notes_private": PRIVATE,
|
||||
}, required=["term", "definition"], desc="One term students meet in this course.")
|
||||
|
||||
EQUATION = obj({
|
||||
"name": s("The name students would use: the global alignment recurrence, the Henderson-Hasselbalch relation.", minLength=1),
|
||||
"tex": s("The relation in LaTeX, without surrounding dollar signs. Rendered as display math.", minLength=1),
|
||||
"says": s("What the relation claims, in words, as a student should be able to state it with the symbols covered. "
|
||||
"Student-facing. " + BRACES, minLength=1),
|
||||
"symbols": arr(obj({"symbol": s("The symbol as it appears in `tex`.", minLength=1),
|
||||
"term": s("Term id, when the quantity has a glossary entry; its definition and units come from there."),
|
||||
"meaning": s("What the symbol stands for, when it has no term."),
|
||||
"units": s("Units, when the symbol has no term or the term gives none.")},
|
||||
required=["symbol"]),
|
||||
"Every symbol in `tex`, in order of first appearance. The validator requires `term` or `meaning` on each."),
|
||||
"implications": arr(obj({"form": {"type": "string", "enum": RELATION_FORMS,
|
||||
"description": "direction: which way the output moves when one input rises. limit: what "
|
||||
"the relation gives at a boundary. scale: whether a stated difference is "
|
||||
"large or negligible on the relation's own scale. dominant_term: which "
|
||||
"term governs an observation. held_fixed: the reference state or normalizer. "
|
||||
"misuse: a result the relation cannot support."},
|
||||
"statement": s("The implication as one student-facing sentence. " + BRACES, minLength=1)},
|
||||
required=["form", "statement"]),
|
||||
"What the relation says that a question can test without evaluating it. These are the raw material "
|
||||
"for level 2 and 3 targets on a relation, and the rendered 'what it tells you' list."),
|
||||
"assumes": arr({"type": "string"}, "Conditions that must hold for the relation to apply, one sentence each. Student-facing."),
|
||||
"fails_when": arr({"type": "string"}, "Cases where the relation breaks or misleads, one sentence each. Student-facing. A "
|
||||
"level 4 item often hands students a wrong result and asks which assumption failed."),
|
||||
"recall": {"type": "boolean", "description": "Students are expected to know this relation from memory. Whether an exam "
|
||||
"may print it is course policy (`policy.exam_conditions.equations`)."},
|
||||
"source": CITE, "status": STATUS, "tags": TAGS, "notes_private": PRIVATE,
|
||||
}, required=["name", "tex", "says"], desc="One relation students meet in this course.")
|
||||
|
||||
VALUE = obj({
|
||||
"name": s("The quantity, specifically: free energy per ten-fold concentration ratio at 37 °C.", minLength=1),
|
||||
"value": {"type": "number", "description": "The value as taught (rounded as students learn it)."},
|
||||
"range": {"type": "array", "items": {"type": "number"}, "minItems": 2, "maxItems": 2,
|
||||
"description": "Low and high, when the course teaches a range rather than one value."},
|
||||
"units": s("Units, as printed."),
|
||||
"say": s("The wording every material uses for it: 'about 6 kJ/mol'. Prose that writes {val-...} renders this.", minLength=1),
|
||||
"exact": {"type": "number", "description": "The unrounded value, for explanations and solutions."},
|
||||
"term": s("Term id of the quantity, when it has a glossary entry."),
|
||||
"source": CITE,
|
||||
"conflicts": arr({"type": "string"}, "Regular expressions for variants that must not appear in any student-facing text "
|
||||
"or item, such as '5\\\\.7\\\\s*kJ'. Write one for every variant that has actually turned up."),
|
||||
"recall": {"type": "boolean", "description": "Students are expected to know it. An exam never prints it, and no option or "
|
||||
"neighbouring item may give it away."},
|
||||
"status": STATUS, "tags": TAGS, "notes_private": PRIVATE,
|
||||
}, required=["name", "say"], desc="One number students are taught. The validator requires `value` or `range`.")
|
||||
|
||||
MISCONCEPTION = obj({
|
||||
"belief": s("The wrong idea as a student holds it, in the student's words: 'a lower total energy always means a "
|
||||
"better structure.' Student-facing: the lecture page lists it under common mistakes. " + BRACES, minLength=1),
|
||||
"correction": s("Why it fails and what is true instead, in one to three sentences. Student-facing. " + BRACES, minLength=1),
|
||||
"error_type": None, # filled below
|
||||
"evidence": arr(obj({"kind": {"type": "string",
|
||||
"enum": ["exam", "homework", "poll", "instructor", "literature", "textbook", "persona"],
|
||||
"description": "Where it was seen. textbook: an assigned text states or implies it, so "
|
||||
"the correction must name the framing it replaces rather than contradict "
|
||||
"the text silently. persona: a simulated student, the weakest evidence."},
|
||||
"detail": s("What was seen: 'Exam 2 Q23, 22% chose it.'"),
|
||||
"ref": s("Citation key, for literature or textbook evidence."),
|
||||
"locator": s("Where in that work.")},
|
||||
required=["kind"]),
|
||||
"Where the misconception has been seen, strongest first."),
|
||||
"status": STATUS, "tags": TAGS, "notes_private": PRIVATE,
|
||||
}, required=["belief", "correction"], desc="One named mistake. Slides name it, items build distractors from it, and "
|
||||
"reports group misses by it.")
|
||||
|
||||
REGISTRY_DESCS = {
|
||||
"terms": "Terms by id, `term-...`. Defined once anywhere in the course, conventionally in the objective file whose "
|
||||
"targets first need it. Targets list the terms they need; a lecture page derives its new and earlier terms "
|
||||
"from those lists.",
|
||||
"equations": "Relations by id, `eq-...`. Defined once, conventionally in the objective file whose targets first need it.",
|
||||
"values": "Taught numbers by id, `val-...`. Defined once; every material states a value in its `say` wording.",
|
||||
"misconceptions": "Named mistakes by id, `mis-...`. Defined once; targets list the ones their items draw on, and bank "
|
||||
"options may name the one they encode.",
|
||||
}
|
||||
|
||||
|
||||
def registries():
|
||||
return {"terms": idmap("term", TERM, REGISTRY_DESCS["terms"]),
|
||||
"equations": idmap("eq", EQUATION, REGISTRY_DESCS["equations"]),
|
||||
"values": idmap("val", VALUE, REGISTRY_DESCS["values"]),
|
||||
"misconceptions": idmap("mis", MISCONCEPTION, REGISTRY_DESCS["misconceptions"])}
|
||||
|
||||
|
||||
# ---------------------------------------------------------------- additions to existing objects
|
||||
|
||||
OBJECTIVE_ADD = {
|
||||
"description": s("Two to four sentences, student-facing: what this objective is about, why it matters, and what it builds "
|
||||
"on or leads to. Rendered under the objective on the lecture page. " + BRACES),
|
||||
}
|
||||
|
||||
TARGET_ADD = {
|
||||
"explanation": s("The canonical account a student who has met this target could give, in two to four sentences: the rule "
|
||||
"or mechanism, what changes the outcome, and when it holds. Student-facing. Not a worked example. The "
|
||||
"lecture brief expands it; slides and items are checked against it. " + BRACES),
|
||||
"terms": arr(ID_LIST, "Term ids a student needs to meet this target. A term is new on the first lecture (in teaching "
|
||||
"order) whose targets list it, and listed as earlier vocabulary on later ones."),
|
||||
"equations": arr(ID_LIST, "Equation ids this target turns on."),
|
||||
"values": arr(ID_LIST, "Value ids this target uses."),
|
||||
"misconceptions": arr(ID_LIST, "Misconception ids an item on this target is most likely to draw on. Distractors are built "
|
||||
"from them, and the lecture names them."),
|
||||
"authoring": obj({
|
||||
"ceiling_item": s("The most demanding fair item at the ceiling, in one sentence: the evidence for the ceiling."),
|
||||
"supplied": arr({"type": "string"}, "What an item on this target hands the student: the data, the scheme, a value."),
|
||||
"constraints": arr({"type": "string"}, "Conditions an item's stem must meet to stay fair, which the validator cannot "
|
||||
"see: 'keep sequences to four bases, or supply a partly filled matrix'."),
|
||||
"number_work": s("The arithmetic an item needs, the operation and roughly how long it takes. Omit when there is none."),
|
||||
"relation_form": {"type": "string", "enum": RELATION_FORMS,
|
||||
"description": "When the target tests a relation without evaluating it, which form it uses."},
|
||||
"examples": arr({"type": "string"}, "Named cases that teach this target in the lecture or the readings, kept out of "
|
||||
"the target text so the target transfers to a case students have not seen."),
|
||||
}, desc="Notes for whoever writes items, slides, or the brief from this target. Instructor-facing: never rendered on a "
|
||||
"student page or exported where a student can see it."),
|
||||
}
|
||||
|
||||
MATERIAL = obj({
|
||||
"kind": {"type": "string", "enum": ["slides", "brief", "notes", "notebook", "recording", "homework", "other"]},
|
||||
"title": s("Link text. Defaults to the kind."),
|
||||
"url": s("Where it lives.", minLength=1),
|
||||
}, required=["kind", "url"])
|
||||
|
||||
LECTURE_ADD = {
|
||||
"description": s("The lecture in two to four sentences, student-facing: what it covers and the arc its objectives follow. "
|
||||
"The lecture page opens with it. " + BRACES),
|
||||
"materials": arr(MATERIAL, "Links the lecture page lists beside the readings: slides, the brief, notebooks, the recording. "
|
||||
"`slides_url` is the older single-link form and still loads."),
|
||||
}
|
||||
|
||||
READING_ADD = {
|
||||
"minutes": {"type": "integer", "minimum": 1, "description": "Estimated reading time, for the lecture page's workload line."},
|
||||
}
|
||||
|
||||
POLICY_ADD = {
|
||||
"exam_conditions": obj({
|
||||
"closed_book": {"type": "boolean"},
|
||||
"calculator": {"type": "boolean", "description": "false: no item may need arithmetic beyond a few seconds, and "
|
||||
"`target_text_forbid` usually bans words that promise a calculation."},
|
||||
"equations": {"type": "string", "enum": ["never_printed", "sheet", "in_stem"],
|
||||
"description": "Whether a relation an item turns on may appear: never (students bring the relation), "
|
||||
"on a supplied sheet, or in the stem."},
|
||||
"formats": arr({"type": "string", "enum": ["single_best_answer", "multiple_response", "true_false", "open_response"]},
|
||||
"Item formats exams use now. Ceilings are still set by the most demanding fair item in any format."),
|
||||
"seconds_per_item": {"type": "number", "exclusiveMinimum": 0.0, "description": "The time budget an item is written to."},
|
||||
}, desc="How exams are sat, as students were told. Pipelines and the linter read these instead of assuming one course's rules."),
|
||||
"blueprints": {"type": "object", "description": "Named default blueprints (module, final), as published to students. An "
|
||||
"assessment's own `blueprint` wins.",
|
||||
"additionalProperties": obj({
|
||||
"level_counts": {"type": "object", "additionalProperties": {"type": "integer", "minimum": 0},
|
||||
"description": "Scored items at each level, keyed by level number."},
|
||||
"bonus_counts": {"type": "object", "additionalProperties": {"type": "integer", "minimum": 0}},
|
||||
"minutes": {"type": "number", "exclusiveMinimum": 0.0}}, required=["level_counts"])},
|
||||
"levels": {"type": "object", "description": "The course's own names and one-line descriptions for levels 1 to 5, as "
|
||||
"students were told them. Lecture pages label ceilings with these; absent, "
|
||||
"the generic Bloom names are used.",
|
||||
"propertyNames": {"pattern": "^[1-5]$"},
|
||||
"additionalProperties": obj({"name": s("Definitions, Concepts, Application ...", minLength=1),
|
||||
"description": s("One line, as published.")}, required=["name"])},
|
||||
"target_text_forbid": arr({"type": "string"}, "Regular expressions that must not match objective or target text, with "
|
||||
"the reason in a comment beside them (for example '\\\\bcalculat' when "
|
||||
"exams are calculator-free). The linter reports every match."),
|
||||
}
|
||||
|
||||
|
||||
def add_props(target, extra):
|
||||
target["properties"].update(copy.deepcopy(extra))
|
||||
|
||||
|
||||
# ---------------------------------------------------------------- bank (error_type enum shared with misconceptions)
|
||||
|
||||
bank = load("bank.schema.json")
|
||||
opt = bank["properties"]["items"]["items"]["properties"]["options"]["items"]
|
||||
ERROR_TYPES = copy.deepcopy(opt["properties"]["error_type"])
|
||||
ERROR_TYPES["description"] = ERROR_TYPES["description"].replace(
|
||||
"What kind of mistake this distractor is designed to catch.", "What kind of mistake it is, in the bank's terms.")
|
||||
MISCONCEPTION["properties"]["error_type"] = ERROR_TYPES
|
||||
opt["properties"]["misconception_id"] = {
|
||||
"type": "string", "pattern": "^mis-[a-z0-9]+(-[a-z0-9]+)*$",
|
||||
"description": "The registry misconception this distractor encodes. Reports group misses by it across items; the "
|
||||
"option's own `misconception` text, when present, overrides the registry's wording for this item."}
|
||||
opt["properties"]["misconception"]["description"] = (
|
||||
"The specific wrong belief that leads here. This text is what student reports use, so write it as a completion of "
|
||||
"'students pick this when ...'. Optional when `misconception_id` is set: the registry's `belief` is used.")
|
||||
dump("bank.schema.json", bank)
|
||||
|
||||
# ---------------------------------------------------------------- objective fragment
|
||||
|
||||
objective = load("objective.schema.json")
|
||||
add_props(objective["properties"]["learning_objectives"]["additionalProperties"], OBJECTIVE_ADD)
|
||||
add_props(objective["properties"]["learning_targets"]["additionalProperties"], TARGET_ADD)
|
||||
objective["properties"].update(registries())
|
||||
objective["description"] = ("One learning objective, the learning targets it decomposes into, and the terms, equations, "
|
||||
"values, and misconceptions its targets first need. A fragment of the course file, merged on load.")
|
||||
dump("objective.schema.json", objective)
|
||||
|
||||
# ---------------------------------------------------------------- lecture fragment
|
||||
|
||||
lecture = load("lecture.schema.json")
|
||||
lec = lecture["properties"]["lectures"]["additionalProperties"]
|
||||
add_props(lec, LECTURE_ADD)
|
||||
reading_obj = lec["properties"]["readings"]["items"]["oneOf"][1]
|
||||
add_props(reading_obj, READING_ADD)
|
||||
for k in ("summary", "focus", "skip"):
|
||||
reading_obj["properties"][k]["description"] += " " + BRACES
|
||||
dump("lecture.schema.json", lecture)
|
||||
|
||||
# ---------------------------------------------------------------- course file
|
||||
|
||||
course = load("course.schema.json")
|
||||
cp = course["properties"]
|
||||
add_props(cp["learning_objectives"]["additionalProperties"], OBJECTIVE_ADD)
|
||||
add_props(cp["learning_targets"]["additionalProperties"], TARGET_ADD)
|
||||
add_props(cp["lectures"]["additionalProperties"], LECTURE_ADD)
|
||||
c_reading = cp["lectures"]["additionalProperties"]["properties"]["readings"]["items"]["oneOf"][1]
|
||||
add_props(c_reading, READING_ADD)
|
||||
for k in ("summary", "focus", "skip"):
|
||||
c_reading["properties"][k]["description"] += " " + BRACES
|
||||
add_props(cp["policy"], POLICY_ADD)
|
||||
cp.update(registries())
|
||||
cp["schema_version"]["description"] = "Format version; currently 2.1."
|
||||
course["description"] = ("Course identity, policy, and the registries that item and assessment files reference by id: "
|
||||
"objectives, targets, lectures, references, stimuli, terms, equations, values, and misconceptions.")
|
||||
dump("course.schema.json", course)
|
||||
|
||||
# ---------------------------------------------------------------- glossary fragment (new)
|
||||
|
||||
glossary = {
|
||||
"$id": "https://coursebank.dev/schema/glossary.schema.json",
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"title": "coursebank glossary file",
|
||||
"type": "object",
|
||||
"additionalProperties": False,
|
||||
"description": "Terms, equations, values, and misconceptions that belong to no single objective: cross-cutting entries, "
|
||||
"and everything `coursebank migrate glossary` brings in from terms.yaml and values.yaml until each entry "
|
||||
"is moved to the objective file whose targets first need it. A fragment of the course file, merged on load.",
|
||||
"properties": dict(registries(), schema_version={"type": ["string", "number"],
|
||||
"description": "Declared in course.yaml; fragments inherit it."}),
|
||||
}
|
||||
dump("glossary.schema.json", glossary)
|
||||
|
||||
# ---------------------------------------------------------------- unchanged, except the version line
|
||||
|
||||
references = load("references.schema.json")
|
||||
references["properties"]["schema_version"]["description"] = "Format version; currently 2.1. Declared in course.yaml; fragments inherit it."
|
||||
dump("references.schema.json", references)
|
||||
for name in ("assessment.schema.json", "calibration.schema.json", "measurements.schema.json"):
|
||||
dump(name, load(name))
|
||||
|
||||
print("wrote", ", ".join(sorted(p.name for p in OUT.glob("*.json"))))
|
||||
@@ -0,0 +1,25 @@
|
||||
# What `coursebank migrate glossary --terms terms.yaml --values values.yaml` should write (field order may differ).
|
||||
# Dropped and reported: terms[decade].first (L2.1) and values[per-decade].lectures ([L2.1, L2.4, L2.5]), both derived
|
||||
# from targets in 2.1; renamed ids decade -> term-decade and per-decade -> val-per-decade.
|
||||
terms:
|
||||
term-decade:
|
||||
term: decade
|
||||
definition: a factor of ten in a concentration ratio or an equilibrium constant
|
||||
kind: coined
|
||||
textbook:
|
||||
- { term: order of magnitude, ref: KKW, locator: "§10.10" }
|
||||
- { term: ten-fold }
|
||||
variants: [decades]
|
||||
exam_wording: ten-fold
|
||||
status: proposed
|
||||
values:
|
||||
val-per-decade:
|
||||
name: free energy per ten-fold concentration ratio at 37 °C
|
||||
value: 6
|
||||
units: kJ/mol
|
||||
say: about 6 kJ/mol
|
||||
exact: 5.9
|
||||
source: { ref: KKW, locator: "§10.10" }
|
||||
conflicts: ['5\.7\s*kJ', '5\.8\s*kJ']
|
||||
recall: true
|
||||
status: proposed
|
||||
@@ -0,0 +1,13 @@
|
||||
schema_version: "1.0"
|
||||
terms:
|
||||
- id: decade
|
||||
course: decade
|
||||
variants: [decades]
|
||||
kind: coined
|
||||
textbook:
|
||||
- { term: order of magnitude, ref: KKW, locator: "§10.10" }
|
||||
- { term: ten-fold }
|
||||
meaning: a factor of ten in a concentration ratio or an equilibrium constant
|
||||
first: L2.1
|
||||
exam_wording: ten-fold
|
||||
status: proposed
|
||||
@@ -0,0 +1,13 @@
|
||||
schema_version: "1.0"
|
||||
values:
|
||||
- id: per-decade
|
||||
name: free energy per ten-fold concentration ratio at 37 °C
|
||||
value: 6
|
||||
units: kJ/mol
|
||||
say: about 6 kJ/mol
|
||||
exact: 5.9
|
||||
source: { ref: KKW, locator: "§10.10" }
|
||||
lectures: [L2.1, L2.4, L2.5]
|
||||
conflicts: ['5\.7\s*kJ', '5\.8\s*kJ']
|
||||
recall: true
|
||||
status: proposed
|
||||
@@ -0,0 +1,19 @@
|
||||
# A 2.0 lecture fragment. It must still validate under 2.1.
|
||||
lectures:
|
||||
l09:
|
||||
title: Pairwise alignment
|
||||
unit: u1
|
||||
slides_url: https://example.edu/slides/l09
|
||||
teaches:
|
||||
- lo-alignment-scoring
|
||||
- lo-alignment-recurrence
|
||||
readings:
|
||||
- ref: durbin1998biological
|
||||
locator: 'ch. 2'
|
||||
targets: [t-align-matrix-terms, t-align-local-vs-global, t-align-fill-matrix]
|
||||
summary: >-
|
||||
Introduces the alignment matrix and the recurrence, then contrasts the global and local fills.
|
||||
focus: >-
|
||||
Fill one small matrix by hand and follow the traceback.
|
||||
skip: >-
|
||||
Gloss the affine-gap extension. It comes in a later lecture.
|
||||
@@ -0,0 +1,22 @@
|
||||
# A 2.0 objective fragment (from the objectives prompt's worked shape). It must still validate under 2.1.
|
||||
learning_objectives:
|
||||
lo-alignment-recurrence:
|
||||
text: 'Use the dynamic-programming recurrence to produce an optimal alignment, and predict how the result moves when the scoring changes.'
|
||||
unit: u1
|
||||
level_ceiling: 3
|
||||
prerequisites: [lo-alignment-scoring]
|
||||
tags: [alignment, algorithms]
|
||||
|
||||
learning_targets:
|
||||
t-align-fill-matrix:
|
||||
text: 'Determine the optimal global alignment score for a short pair of sequences by filling the matrix from the recurrence, and read the alignment off the traceback.'
|
||||
objective: lo-alignment-recurrence
|
||||
level_ceiling: 3
|
||||
prerequisites: [t-align-matrix-terms]
|
||||
tags: [alignment, algorithms]
|
||||
t-align-gap-penalty-effect:
|
||||
text: 'Predict how raising the gap penalty changes the optimal path through the matrix.'
|
||||
objective: lo-alignment-recurrence
|
||||
level_ceiling: 3
|
||||
prerequisites: [t-align-fill-matrix]
|
||||
tags: [alignment]
|
||||
@@ -0,0 +1,16 @@
|
||||
# banks/alignment.yaml (coursebank 2.1): one option names the registry misconception it encodes
|
||||
bank: { id: alignment, title: Alignment }
|
||||
items:
|
||||
- id: q-align-which-scores-higher
|
||||
status: draft # coursebank requires a status on every item; an approved one also needs cognitive_process, sources, and design
|
||||
level: 2
|
||||
stem: 'Two alignments of the same pair have the same number of matching columns. Why can their scores differ?'
|
||||
learning_targets: [t-align-score-columns]
|
||||
options:
|
||||
- { id: o-columns-all-count, text: 'Mismatches and gaps also add to the score, so the other columns differ.', correct: true }
|
||||
- id: o-matches-only
|
||||
text: 'They cannot differ; the score counts matching columns.'
|
||||
misconception_id: mis-only-matches-count
|
||||
error_type: incomplete_understanding
|
||||
- { id: o-length, text: 'The longer alignment always scores lower.', misconception: 'students pick this when they think length alone is penalized' }
|
||||
- { id: o-order, text: 'The score depends on which sequence is written on top.', error_type: plausible_irrelevant, misconception: 'students pick this when they confuse the matrix layout with the score' }
|
||||
@@ -0,0 +1,28 @@
|
||||
# course.yaml (coursebank 2.1): identity, policy, and units; the new policy blocks shown in full
|
||||
schema_version: '2.1'
|
||||
course:
|
||||
code: BIOSC 1540
|
||||
title: Computational Biology
|
||||
term: 2027s
|
||||
policy:
|
||||
options_per_item: 4
|
||||
min_items_for_mastery: 2
|
||||
mastery_threshold: 0.75
|
||||
exam_conditions:
|
||||
closed_book: true
|
||||
calculator: false
|
||||
equations: never_printed
|
||||
formats: [single_best_answer]
|
||||
seconds_per_item: 120
|
||||
blueprints:
|
||||
module: { level_counts: { '1': 6, '2': 18, '3': 9, '4': 3 }, bonus_counts: { '5': 1 }, minutes: 75 }
|
||||
final: { level_counts: { '1': 8, '2': 24, '3': 12, '4': 4 }, bonus_counts: { '5': 1 }, minutes: 110 }
|
||||
levels:
|
||||
'1': { name: Definitions, description: 'Match a term to its name or definition.' }
|
||||
'2': { name: Concepts, description: 'Explain how something works, as it normally is.' }
|
||||
'3': { name: Application, description: 'Change one thing and follow it to the result.' }
|
||||
'4': { name: Analytical, description: 'Weigh several interacting conditions at once.' }
|
||||
'5': { name: Synthesis, description: 'Extend to an unseen case, or judge competing explanations.' }
|
||||
target_text_forbid: ['\bcomput', '\bcalculat', '\bestimat'] # calculator-free exams: no text may promise a calculation
|
||||
units:
|
||||
- { id: u1, title: Sequences and alignment }
|
||||
@@ -0,0 +1,26 @@
|
||||
# glossary.yaml (coursebank 2.1)
|
||||
# Entries brought in by `coursebank migrate glossary --terms terms.yaml --values values.yaml`, waiting to be moved to
|
||||
# the objective file whose targets first need them, plus anything genuinely cross-cutting.
|
||||
terms:
|
||||
term-decade:
|
||||
term: decade
|
||||
definition: 'A factor of ten in a concentration ratio or an equilibrium constant.'
|
||||
kind: coined
|
||||
textbook:
|
||||
- { term: order of magnitude, ref: KKW, locator: '§10.10' }
|
||||
- { term: ten-fold }
|
||||
variants: [decades]
|
||||
exam_wording: ten-fold
|
||||
status: proposed
|
||||
values:
|
||||
val-per-decade:
|
||||
name: free energy per ten-fold concentration ratio at 37 °C
|
||||
value: 6
|
||||
units: kJ/mol
|
||||
say: about 6 kJ/mol
|
||||
exact: 5.9
|
||||
term: term-decade
|
||||
source: { ref: KKW, locator: '§10.10' }
|
||||
conflicts: ['5\.7\s*kJ', '5\.8\s*kJ']
|
||||
recall: true
|
||||
status: proposed
|
||||
@@ -0,0 +1,73 @@
|
||||
<!-- What prototype/check21.py derives for l09: the content and order the 2.1 lecture page should show. Layout is the renderer's. -->
|
||||
# l09: Pairwise alignment
|
||||
|
||||
How alike are two sequences? This lecture scores one alignment column by column, shows that there are far too many alignments to score one at a time (about 10^{59} for two 100-letter sequences), and builds the table that finds the best one anyway. It ends on when to align end to end and when to look for a shared region.
|
||||
|
||||
## Account for how an alignment is scored, and choose a scoring scheme and gap penalty suited to a given pair of sequences.
|
||||
|
||||
Before anything can find the best alignment, "best" needs a number. This objective is that number: a score added up column by column, where the [gap penalty] and the [substitution score] decide what a good alignment looks like.
|
||||
|
||||
- **Define the alignment matrix, the scoring scheme, and the gap penalty, and identify each on a filled matrix.** (Definitions)
|
||||
The [alignment matrix] puts one sequence along the top and the other down the side. The scoring scheme gives a [substitution score] to every pair of letters and a [gap penalty] to every gap.
|
||||
- **Explain why two alignments of one pair with the same number of matches can score differently under one scheme.** (Concepts)
|
||||
An alignment's score is the sum over its columns. Matches add, mismatches cost a little and gaps cost more, so alignments with equal matches differ in what their other columns cost.
|
||||
|
||||
## Use the dynamic-programming recurrence to produce an optimal alignment, and predict how the result moves when the scoring changes.
|
||||
|
||||
Two short sequences already have more alignments than anyone could score one at a time. The recurrence finds the best one anyway, by scoring every pair of prefixes once and reusing those scores ([the global alignment recurrence]). This objective is the method the rest of the unit builds on: database search in the next lecture is this table with most of its cells skipped.
|
||||
|
||||
- **Given a match, mismatch, and gap scheme and two short sequences, determine the optimal global alignment score by filling the matrix from the recurrence, and read the alignment off the traceback.** (Application)
|
||||
Each cell holds the best score for aligning the two prefixes that end there, and it is the best of three offers: the diagonal neighbour plus the score of pairing the two letters, or either other neighbour minus the [gap penalty]. The first row and column are all gaps. The bottom-right cell is the optimal score, and following each cell back to the neighbour that won it gives the alignment ([traceback]).
|
||||
- **Predict how raising the gap penalty changes the optimal path through the matrix.** (Application)
|
||||
A larger [gap penalty] makes every horizontal or vertical step cost more, so the diagonal wins more cells and the optimal path uses fewer gaps, accepting mismatches it would have avoided before.
|
||||
- **Given two sequences that share one conserved region, and the global and local optimal alignments of them, determine which alignment answers whether the region is shared and which assumption the other one violates.** (Analytical)
|
||||
Global alignment assumes the sequences are related end to end, so it pays for every unrelated flank and can bury a shared region under gap and mismatch costs. Local alignment drops that assumption: any cell may restart at zero, so the best region is found wherever it sits.
|
||||
|
||||
## New terms
|
||||
|
||||
- **alignment matrix**: A table with one sequence along the top and the other down the side, where each cell holds the best score for aligning the two prefixes that end there. (textbooks: dynamic programming matrix)
|
||||
- **gap**: A position where one sequence has a letter and the other has a dash.
|
||||
- **gap penalty** $d$: The score subtracted for each position where one sequence is aligned against a [gap].
|
||||
- **substitution score** $s(a,b)$: The score for pairing two letters in one column: positive for pairs that are often swapped in related sequences, negative for pairs that rarely are.
|
||||
- **traceback**: Following each cell of a filled alignment matrix back to the neighbour that gave it its score, from the last cell to the first, to read off the alignment.
|
||||
- **global alignment**: An alignment of two sequences from end to end, every letter of both included.
|
||||
- **local alignment**: The best-scoring alignment of any part of one sequence with any part of the other.
|
||||
|
||||
## Equations
|
||||
|
||||
### the global alignment recurrence
|
||||
|
||||
$$F(i,j) = \max\begin{cases} F(i-1,j-1) + s(x_i, y_j) \\ F(i-1,j) - d \\ F(i,j-1) - d \end{cases}$$
|
||||
|
||||
The best score for the first i letters of one sequence against the first j of the other is the best of three moves into that cell: pair the two last letters, or put a gap against one of them.
|
||||
|
||||
- F(i,j): the best score for aligning the first i letters of x with the first j letters of y
|
||||
- s(x_i, y_j): substitution score
|
||||
- d: gap penalty
|
||||
- What it tells you (direction): Raising [gap penalty] makes the diagonal win more cells, so optimal alignments use fewer gaps.
|
||||
- What it tells you (held fixed): Two optimal scores can be compared only under the same scoring scheme; the scheme sets the scale.
|
||||
- What it tells you (misuse): A high global score does not show that any one region is shared: unrelated flanks lower it and a strong region can hide in it.
|
||||
- Assumes: Each gap position costs the same, whatever its neighbours.
|
||||
- Assumes: A column's score depends only on the two letters in it.
|
||||
- Assumes: Both sequences are related from end to end.
|
||||
- Fails when: Gaps come in long runs, which a linear penalty charges too much for; an affine penalty fits better.
|
||||
- Fails when: The sequences share only a region, which global alignment can bury; local alignment finds it.
|
||||
|
||||
## Numbers to know
|
||||
|
||||
- number of global alignments of two 100-letter sequences: about 10^{59}
|
||||
|
||||
## Common mistakes
|
||||
|
||||
- *An alignment score counts the matching positions, so the alignment with the most matches scores highest.* Every column counts: matches add, mismatches cost a little, and gaps cost more, so two alignments with the same matches can score differently.
|
||||
- *A local alignment is the global alignment with its unmatched ends trimmed off.* Local alignment changes the recurrence: any cell can restart at zero, so its best region can sit where the global path never passes.
|
||||
|
||||
## Readings
|
||||
|
||||
- Durbin ch. 2 (40 min): Fill one small matrix by hand and follow the traceback (T t-align-fill-matrix). Watch what changes at the matrix boundaries and where the traceback starts; that is the whole global-versus-local distinction.
|
||||
|
||||
## Materials
|
||||
|
||||
- slides: https://example.edu/slides/l09
|
||||
- Lecture brief: https://example.edu/briefs/l09
|
||||
- Fill a matrix in Python: https://example.edu/notebooks/l09.ipynb
|
||||
@@ -0,0 +1,28 @@
|
||||
# lectures/l09.yaml (coursebank 2.1)
|
||||
lectures:
|
||||
l09:
|
||||
title: Pairwise alignment
|
||||
unit: u1
|
||||
description: >-
|
||||
How alike are two sequences? This lecture scores one alignment column by column, shows that there are far too
|
||||
many alignments to score one at a time ({val-alignment-count-100} for two 100-letter sequences), and builds the
|
||||
table that finds the best one anyway. It ends on when to align end to end and when to look for a shared region.
|
||||
teaches:
|
||||
- lo-alignment-scoring
|
||||
- lo-alignment-recurrence
|
||||
materials:
|
||||
- { kind: slides, url: 'https://example.edu/slides/l09' }
|
||||
- { kind: brief, title: 'Lecture brief', url: 'https://example.edu/briefs/l09' }
|
||||
- { kind: notebook, title: 'Fill a matrix in Python', url: 'https://example.edu/notebooks/l09.ipynb' }
|
||||
readings:
|
||||
- ref: durbin1998biological
|
||||
locator: 'ch. 2'
|
||||
minutes: 40
|
||||
targets: [t-align-matrix-terms, t-align-score-columns, t-align-fill-matrix, t-align-local-vs-global-diagnose]
|
||||
summary: >-
|
||||
Introduces the alignment matrix and {eq-global-recurrence}, then contrasts the global and local fills.
|
||||
focus: >-
|
||||
Fill one small matrix by hand and follow the traceback ({t-align-fill-matrix}). Watch what changes at the
|
||||
matrix boundaries and where the traceback starts; that is the whole global-versus-local distinction.
|
||||
skip: >-
|
||||
Gloss the affine-gap extension. It comes in a later lecture.
|
||||
@@ -0,0 +1,129 @@
|
||||
# objectives/lo-alignment-recurrence.yaml (coursebank 2.1)
|
||||
#
|
||||
# One objective, its targets, and the glossary entries its targets are the first to need. The terms, equation,
|
||||
# value, and misconceptions defined here are course-wide: any later target lists them by id, and nothing redefines them.
|
||||
# Fields marked student-facing render on the lecture page; `authoring` and `notes_private` never do.
|
||||
|
||||
learning_objectives:
|
||||
lo-alignment-recurrence:
|
||||
text: 'Use the dynamic-programming recurrence to produce an optimal alignment, and predict how the result moves when the scoring changes.'
|
||||
description: >-
|
||||
Two short sequences already have more alignments than anyone could score one at a time. The recurrence finds the
|
||||
best one anyway, by scoring every pair of prefixes once and reusing those scores ({eq-global-recurrence}). This
|
||||
objective is the method the rest of the unit builds on: database search in the next lecture is this table with
|
||||
most of its cells skipped.
|
||||
unit: u1
|
||||
level_ceiling: 4
|
||||
prerequisites: [lo-alignment-scoring]
|
||||
tags: [alignment, algorithms]
|
||||
|
||||
learning_targets:
|
||||
t-align-fill-matrix:
|
||||
text: 'Given a match, mismatch, and gap scheme and two short sequences, determine the optimal global alignment score by filling the matrix from the recurrence, and read the alignment off the traceback.'
|
||||
objective: lo-alignment-recurrence
|
||||
level_ceiling: 3
|
||||
prerequisites: [t-align-matrix-terms]
|
||||
tags: [alignment, algorithms]
|
||||
explanation: >-
|
||||
Each cell holds the best score for aligning the two prefixes that end there, and it is the best of three
|
||||
offers: the diagonal neighbour plus the score of pairing the two letters, or either other neighbour minus the
|
||||
{term-gap-penalty}. The first row and column are all gaps. The bottom-right cell is the optimal score, and
|
||||
following each cell back to the neighbour that won it gives the alignment ({term-traceback}).
|
||||
terms: [term-alignment-matrix, term-gap-penalty, term-substitution-score, term-traceback]
|
||||
equations: [eq-global-recurrence]
|
||||
values: [val-alignment-count-100]
|
||||
misconceptions: [mis-only-matches-count]
|
||||
authoring:
|
||||
ceiling_item: 'Supply a 3 by 3 matrix with all but the last cell filled and ask for the last cell and the traceback it starts.'
|
||||
supplied: ['the scoring scheme', 'the two sequences', 'all but one or two cells of the matrix']
|
||||
constraints: ['keep each sequence to four letters or fewer, or supply a partly filled matrix: a full 5 by 5 fill runs past the two-minute budget']
|
||||
number_work: 'one addition and a three-way comparison per cell, a few seconds each'
|
||||
examples: ['the two short globin fragments in the lecture worked example']
|
||||
|
||||
t-align-gap-penalty-effect:
|
||||
text: 'Predict how raising the gap penalty changes the optimal path through the matrix.'
|
||||
objective: lo-alignment-recurrence
|
||||
level_ceiling: 3
|
||||
prerequisites: [t-align-fill-matrix]
|
||||
tags: [alignment]
|
||||
explanation: >-
|
||||
A larger {term-gap-penalty} makes every horizontal or vertical step cost more, so the diagonal wins more cells
|
||||
and the optimal path uses fewer gaps, accepting mismatches it would have avoided before.
|
||||
terms: [term-gap-penalty]
|
||||
equations: [eq-global-recurrence]
|
||||
authoring:
|
||||
ceiling_item: 'Show the optimal path under d = 1 and ask which path wins under d = 4.'
|
||||
supplied: ['the two sequences', 'the optimal path under the lower penalty']
|
||||
relation_form: direction
|
||||
|
||||
t-align-local-vs-global-diagnose:
|
||||
text: 'Given two sequences that share one conserved region, and the global and local optimal alignments of them, determine which alignment answers whether the region is shared and which assumption the other one violates.'
|
||||
objective: lo-alignment-recurrence
|
||||
level_ceiling: 4
|
||||
prerequisites: [t-align-fill-matrix]
|
||||
tags: [alignment]
|
||||
explanation: >-
|
||||
Global alignment assumes the sequences are related end to end, so it pays for every unrelated flank and can bury a
|
||||
shared region under gap and mismatch costs. Local alignment drops that assumption: any cell may restart at zero,
|
||||
so the best region is found wherever it sits.
|
||||
terms: [term-global-alignment, term-local-alignment]
|
||||
equations: [eq-global-recurrence]
|
||||
misconceptions: [mis-local-is-trimmed-global]
|
||||
authoring:
|
||||
ceiling_item: 'Give both alignments and their scores, and ask which supports the claim that the region is shared and why the other misleads.'
|
||||
supplied: ['both sequences', 'both optimal alignments with their scores']
|
||||
relation_form: misuse
|
||||
|
||||
terms:
|
||||
term-traceback:
|
||||
term: traceback
|
||||
definition: 'Following each cell of a filled alignment matrix back to the neighbour that gave it its score, from the last cell to the first, to read off the alignment.'
|
||||
term-global-alignment:
|
||||
term: global alignment
|
||||
definition: 'An alignment of two sequences from end to end, every letter of both included.'
|
||||
term-local-alignment:
|
||||
term: local alignment
|
||||
definition: 'The best-scoring alignment of any part of one sequence with any part of the other.'
|
||||
|
||||
equations:
|
||||
eq-global-recurrence:
|
||||
name: the global alignment recurrence
|
||||
tex: 'F(i,j) = \max\begin{cases} F(i-1,j-1) + s(x_i, y_j) \\ F(i-1,j) - d \\ F(i,j-1) - d \end{cases}'
|
||||
says: >-
|
||||
The best score for the first i letters of one sequence against the first j of the other is the best of three
|
||||
moves into that cell: pair the two last letters, or put a gap against one of them.
|
||||
symbols:
|
||||
- { symbol: 'F(i,j)', meaning: 'the best score for aligning the first i letters of x with the first j letters of y' }
|
||||
- { symbol: 's(x_i, y_j)', term: term-substitution-score }
|
||||
- { symbol: 'd', term: term-gap-penalty }
|
||||
implications:
|
||||
- { form: direction, statement: 'Raising {term-gap-penalty} makes the diagonal win more cells, so optimal alignments use fewer gaps.' }
|
||||
- { form: held_fixed, statement: 'Two optimal scores can be compared only under the same scoring scheme; the scheme sets the scale.' }
|
||||
- { form: misuse, statement: 'A high global score does not show that any one region is shared: unrelated flanks lower it and a strong region can hide in it.' }
|
||||
assumes:
|
||||
- 'Each gap position costs the same, whatever its neighbours.'
|
||||
- 'A column''s score depends only on the two letters in it.'
|
||||
- 'Both sequences are related from end to end.'
|
||||
fails_when:
|
||||
- 'Gaps come in long runs, which a linear penalty charges too much for; an affine penalty fits better.'
|
||||
- 'The sequences share only a region, which global alignment can bury; local alignment finds it.'
|
||||
recall: true
|
||||
source: { ref: durbin1998biological, locator: 'ch. 2' }
|
||||
|
||||
values:
|
||||
val-alignment-count-100:
|
||||
name: number of global alignments of two 100-letter sequences
|
||||
value: 1.0e+59
|
||||
say: 'about 10^{59}'
|
||||
exact: 9.05e+58
|
||||
source: { ref: durbin1998biological, locator: 'ch. 2' }
|
||||
conflicts: ['10\^\{?100\}?\s*alignments']
|
||||
recall: false
|
||||
|
||||
misconceptions:
|
||||
mis-local-is-trimmed-global:
|
||||
belief: 'A local alignment is the global alignment with its unmatched ends trimmed off.'
|
||||
correction: 'Local alignment changes the recurrence: any cell can restart at zero, so its best region can sit where the global path never passes.'
|
||||
error_type: misconception
|
||||
evidence:
|
||||
- { kind: instructor, detail: 'Asked in office hours most terms.' }
|
||||
@@ -0,0 +1,66 @@
|
||||
# objectives/lo-alignment-scoring.yaml (coursebank 2.1)
|
||||
# The first objective l09 teaches. Its targets are the first to need gaps, the gap penalty, substitution scores, and the
|
||||
# "only matches count" mistake, so those entries are defined here; the recurrence objective lists them by id.
|
||||
|
||||
learning_objectives:
|
||||
lo-alignment-scoring:
|
||||
text: 'Account for how an alignment is scored, and choose a scoring scheme and gap penalty suited to a given pair of sequences.'
|
||||
description: >-
|
||||
Before anything can find the best alignment, "best" needs a number. This objective is that number: a score added
|
||||
up column by column, where the {term-gap-penalty} and the {term-substitution-score} decide what a good alignment
|
||||
looks like.
|
||||
unit: u1
|
||||
level_ceiling: 2
|
||||
tags: [alignment]
|
||||
|
||||
learning_targets:
|
||||
t-align-matrix-terms:
|
||||
text: 'Define the alignment matrix, the scoring scheme, and the gap penalty, and identify each on a filled matrix.'
|
||||
objective: lo-alignment-scoring
|
||||
level_ceiling: 1
|
||||
tags: [alignment]
|
||||
explanation: >-
|
||||
The {term-alignment-matrix} puts one sequence along the top and the other down the side. The scoring scheme gives a
|
||||
{term-substitution-score} to every pair of letters and a {term-gap-penalty} to every gap.
|
||||
terms: [term-alignment-matrix, term-gap, term-gap-penalty, term-substitution-score]
|
||||
t-align-score-columns:
|
||||
text: 'Explain why two alignments of one pair with the same number of matches can score differently under one scheme.'
|
||||
objective: lo-alignment-scoring
|
||||
level_ceiling: 2
|
||||
prerequisites: [t-align-matrix-terms]
|
||||
tags: [alignment]
|
||||
explanation: >-
|
||||
An alignment's score is the sum over its columns. Matches add, mismatches cost a little and gaps cost more, so
|
||||
alignments with equal matches differ in what their other columns cost.
|
||||
terms: [term-gap, term-gap-penalty, term-substitution-score]
|
||||
misconceptions: [mis-only-matches-count]
|
||||
|
||||
terms:
|
||||
term-alignment-matrix:
|
||||
term: alignment matrix
|
||||
definition: 'A table with one sequence along the top and the other down the side, where each cell holds the best score for aligning the two prefixes that end there.'
|
||||
kind: renamed
|
||||
textbook:
|
||||
- { term: dynamic programming matrix, ref: durbin1998biological, locator: 'ch. 2' }
|
||||
variants: [alignment matrices]
|
||||
term-gap:
|
||||
term: gap
|
||||
definition: 'A position where one sequence has a letter and the other has a dash.'
|
||||
variants: [gaps]
|
||||
term-gap-penalty:
|
||||
term: gap penalty
|
||||
definition: 'The score subtracted for each position where one sequence is aligned against a {term-gap}.'
|
||||
symbol: '$d$'
|
||||
variants: [gap penalties]
|
||||
term-substitution-score:
|
||||
term: substitution score
|
||||
definition: 'The score for pairing two letters in one column: positive for pairs that are often swapped in related sequences, negative for pairs that rarely are.'
|
||||
symbol: '$s(a,b)$'
|
||||
|
||||
misconceptions:
|
||||
mis-only-matches-count:
|
||||
belief: 'An alignment score counts the matching positions, so the alignment with the most matches scores highest.'
|
||||
correction: 'Every column counts: matches add, mismatches cost a little, and gaps cost more, so two alignments with the same matches can score differently.'
|
||||
error_type: incomplete_understanding
|
||||
evidence:
|
||||
- { kind: persona, detail: 'Incoming-student probe: scored by identity alone.' }
|
||||
@@ -0,0 +1,17 @@
|
||||
references:
|
||||
durbin1998biological:
|
||||
label: Durbin
|
||||
kind: book
|
||||
role: required
|
||||
title: 'Biological Sequence Analysis: Probabilistic Models of Proteins and Nucleic Acids'
|
||||
authors: ['Durbin, Richard', 'Eddy, Sean R.', 'Krogh, Anders', 'Mitchison, Graeme']
|
||||
year: 1998
|
||||
publisher: Cambridge University Press
|
||||
KKW:
|
||||
label: KKW
|
||||
kind: book
|
||||
role: required
|
||||
title: 'The Molecules of Life: Physical and Chemical Principles'
|
||||
authors: ['Kuriyan, John', 'Konforti, Boyana', 'Wemmer, David']
|
||||
year: 2013
|
||||
publisher: Garland Science
|
||||
@@ -0,0 +1,423 @@
|
||||
#!/usr/bin/env python3
|
||||
"""A prototype of coursebank 2.1's new rules, for porting to Rust. Not part of coursebank.
|
||||
|
||||
python3 prototype/check21.py examples/v21 # validate + lint, print findings, exit 1 on errors
|
||||
python3 prototype/check21.py examples/v21 --page l09 # also print the derived lecture-page content for l09
|
||||
|
||||
It loads a course directory the way coursebank does (course.yaml, references.yaml, glossary.yaml, lectures/*.yaml,
|
||||
objectives/*.yaml, banks/*.yaml), merges the registries while remembering which file defined each id, and runs ONLY
|
||||
the rules 2.1 adds. Every rule has a code; SCHEMA-CHANGES.md lists them with the reason for each. The existing 2.0
|
||||
rules (prerequisite cycles, ceilings, reading targets, references) are coursebank's and are not repeated here.
|
||||
"""
|
||||
import argparse
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
import yaml
|
||||
|
||||
REGISTRIES = { # registry -> id prefix (2.1 adds the last four)
|
||||
"learning_objectives": "lo-", "learning_targets": "t-", "terms": "term-", "equations": "eq-", "values": "val-",
|
||||
"misconceptions": "mis-",
|
||||
}
|
||||
GLOSSARY = ("terms", "equations", "values", "misconceptions")
|
||||
BRACE = re.compile(r"\{((?:lo|t|term|eq|val|mis)-[a-z0-9]+(?:-[a-z0-9]+)*)\}")
|
||||
ID_PREFIX_ORDER = ["term-", "eq-", "val-", "mis-", "lo-", "t-"] # longest-first matters: 'term-' before 't-'
|
||||
|
||||
|
||||
def safe_re(pattern, flags=0):
|
||||
"""A compiled pattern, or None when it does not compile (E2107 already reports it)."""
|
||||
try:
|
||||
return re.compile(pattern, flags)
|
||||
except re.error:
|
||||
return None
|
||||
|
||||
|
||||
class Course:
|
||||
def __init__(self, root):
|
||||
self.root = Path(root)
|
||||
self.reg = {k: {} for k in REGISTRIES}
|
||||
self.where = {} # id -> file that defined it
|
||||
self.lectures, self.references, self.policy, self.items = {}, {}, {}, []
|
||||
self.findings = []
|
||||
files = [self.root / "course.yaml", self.root / "references.yaml", self.root / "glossary.yaml",
|
||||
*sorted((self.root / "lectures").glob("*.yaml")), *sorted((self.root / "objectives").glob("*.yaml"))]
|
||||
for f in files:
|
||||
if not f.exists():
|
||||
continue
|
||||
data = yaml.safe_load(f.read_text(encoding="utf-8")) or {}
|
||||
rel = str(f.relative_to(self.root))
|
||||
for reg in REGISTRIES:
|
||||
for i, entry in (data.get(reg) or {}).items():
|
||||
if i in self.where:
|
||||
self.add("E2101", i, f"defined in both {self.where[i]} and {rel}")
|
||||
self.where[i] = rel
|
||||
self.reg[reg][i] = entry
|
||||
self.lectures.update(data.get("lectures") or {})
|
||||
self.references.update(data.get("references") or {})
|
||||
self.policy.update(data.get("policy") or {})
|
||||
for f in sorted((self.root / "banks").glob("*.yaml")):
|
||||
data = yaml.safe_load(f.read_text(encoding="utf-8")) or {}
|
||||
self.items += [(str(f.relative_to(self.root)), it) for it in data.get("items") or []]
|
||||
|
||||
def add(self, code, where, msg):
|
||||
self.findings.append((code, where, msg))
|
||||
|
||||
def kind_of(self, i):
|
||||
for p in ID_PREFIX_ORDER:
|
||||
if i.startswith(p):
|
||||
return {"term-": "terms", "eq-": "equations", "val-": "values", "mis-": "misconceptions",
|
||||
"lo-": "learning_objectives", "t-": "learning_targets"}[p]
|
||||
return None
|
||||
|
||||
def exists(self, reg, i):
|
||||
return i in self.reg[reg]
|
||||
|
||||
# ------------------------------------------------------------- student-facing prose, for brace and conflict checks
|
||||
def prose(self):
|
||||
"""(where, field, text) for every student-facing prose field."""
|
||||
for i, o in self.reg["learning_objectives"].items():
|
||||
yield i, "text", o.get("text")
|
||||
yield i, "description", o.get("description")
|
||||
for i, t in self.reg["learning_targets"].items():
|
||||
yield i, "text", t.get("text")
|
||||
yield i, "explanation", t.get("explanation")
|
||||
for i, t in self.reg["terms"].items():
|
||||
yield i, "definition", t.get("definition")
|
||||
for i, e in self.reg["equations"].items():
|
||||
yield i, "says", e.get("says")
|
||||
for k, imp in enumerate(e.get("implications") or []):
|
||||
yield i, f"implications[{k}]", imp.get("statement")
|
||||
for k, a in enumerate(e.get("assumes") or []):
|
||||
yield i, f"assumes[{k}]", a
|
||||
for k, a in enumerate(e.get("fails_when") or []):
|
||||
yield i, f"fails_when[{k}]", a
|
||||
for i, m in self.reg["misconceptions"].items():
|
||||
yield i, "belief", m.get("belief")
|
||||
yield i, "correction", m.get("correction")
|
||||
for lid, lec in self.lectures.items():
|
||||
yield lid, "description", lec.get("description")
|
||||
for k, r in enumerate(lec.get("readings") or []):
|
||||
if isinstance(r, dict):
|
||||
for f in ("summary", "focus", "skip"):
|
||||
yield lid, f"readings[{k}].{f}", r.get(f)
|
||||
|
||||
def item_text(self):
|
||||
for f, it in self.items:
|
||||
yield f, it.get("id"), "stem", it.get("stem")
|
||||
for o in it.get("options") or []:
|
||||
yield f, it.get("id"), f"option {o.get('id')}", o.get("text")
|
||||
yield f, it.get("id"), f"option {o.get('id')} feedback", o.get("feedback_student")
|
||||
yield f, it.get("id"), "solution", (it.get("solution") or {}).get("explanation")
|
||||
|
||||
# ------------------------------------------------------------- errors
|
||||
def check(self):
|
||||
refs = set(self.references)
|
||||
# E2102 a target's glossary links resolve to the right registry
|
||||
for tid, t in self.reg["learning_targets"].items():
|
||||
for field in GLOSSARY:
|
||||
for x in t.get(field) or []:
|
||||
if not self.exists(field, x):
|
||||
self.add("E2102", tid, f"{field}: {x} is not a declared {field[:-1]}")
|
||||
# E2103 equation symbols: term resolves; term or meaning present
|
||||
for eid, e in self.reg["equations"].items():
|
||||
for s in e.get("symbols") or []:
|
||||
if s.get("term") and not self.exists("terms", s["term"]):
|
||||
self.add("E2103", eid, f"symbol {s.get('symbol')}: term {s['term']} is not declared")
|
||||
if not s.get("term") and not s.get("meaning"):
|
||||
self.add("E2103", eid, f"symbol {s.get('symbol')}: give term or meaning")
|
||||
# E2104 values: value or range; range ordered; term resolves
|
||||
for vid, v in self.reg["values"].items():
|
||||
if v.get("value") is None and not v.get("range"):
|
||||
self.add("E2104", vid, "give value or range")
|
||||
if v.get("range") and v["range"][0] > v["range"][1]:
|
||||
self.add("E2104", vid, "range low is above high")
|
||||
if v.get("term") and not self.exists("terms", v["term"]):
|
||||
self.add("E2104", vid, f"term {v['term']} is not declared")
|
||||
# E2105 citation keys in the new registries resolve
|
||||
for reg in GLOSSARY:
|
||||
for i, e in self.reg[reg].items():
|
||||
cites = [e.get("source") or {}] + list(e.get("textbook") or []) + list(e.get("evidence") or [])
|
||||
for c in cites:
|
||||
if c.get("ref") and c["ref"] not in refs:
|
||||
self.add("E2105", i, f"ref {c['ref']} is not in references")
|
||||
# E2106 brace references resolve
|
||||
for where, field, text in self.prose():
|
||||
for m in BRACE.finditer(text or ""):
|
||||
reg = self.kind_of(m.group(1))
|
||||
if not reg or not self.exists(reg, m.group(1)):
|
||||
self.add("E2106", where, f"{field}: {{{m.group(1)}}} is not declared")
|
||||
# E2107 regular expressions compile
|
||||
for vid, v in self.reg["values"].items():
|
||||
for pat in v.get("conflicts") or []:
|
||||
try:
|
||||
re.compile(pat)
|
||||
except re.error as ex:
|
||||
self.add("E2107", vid, f"conflicts pattern {pat!r}: {ex}")
|
||||
for pat in self.policy.get("target_text_forbid") or []:
|
||||
try:
|
||||
re.compile(pat)
|
||||
except re.error as ex:
|
||||
self.add("E2107", "policy", f"target_text_forbid {pat!r}: {ex}")
|
||||
# E2108 bank options' misconception_id resolves; an option needs misconception text or an id on a distractor
|
||||
for f, it in self.items:
|
||||
for o in it.get("options") or []:
|
||||
mid = o.get("misconception_id")
|
||||
if mid and not self.exists("misconceptions", mid):
|
||||
self.add("E2108", f"{it.get('id')} {o.get('id')}", f"misconception_id {mid} is not declared")
|
||||
return self
|
||||
|
||||
# ------------------------------------------------------------- lints
|
||||
def lint(self):
|
||||
used = {k: set() for k in GLOSSARY}
|
||||
for t in self.reg["learning_targets"].values():
|
||||
for k in GLOSSARY:
|
||||
used[k] |= set(t.get(k) or [])
|
||||
for e in self.reg["equations"].values():
|
||||
used["terms"] |= {s["term"] for s in e.get("symbols") or [] if s.get("term")}
|
||||
for v in self.reg["values"].values():
|
||||
if v.get("term"):
|
||||
used["terms"].add(v["term"])
|
||||
for f, it in self.items:
|
||||
used["misconceptions"] |= {o["misconception_id"] for o in it.get("options") or [] if o.get("misconception_id")}
|
||||
# W2101 an entry no target needs
|
||||
for k in GLOSSARY:
|
||||
for i in self.reg[k]:
|
||||
if i not in used[k]:
|
||||
self.add("W2101", i, f"no target lists it (nor an equation, value, or item); a {k[:-1]} the course does not need")
|
||||
for tid, t in self.reg["terms"].items():
|
||||
# W2102 renamed or coined with no textbook name
|
||||
if t.get("kind") in ("renamed", "coined") and not t.get("textbook"):
|
||||
self.add("W2102", tid, f"{t['kind']} term with no textbook name; students cannot look it up")
|
||||
# W2103 coined with no exam wording
|
||||
if t.get("kind") == "coined" and not t.get("exam_wording"):
|
||||
self.add("W2103", tid, "coined term with no exam_wording")
|
||||
# W2104 circular definition
|
||||
forms = [t.get("term", "")] + list(t.get("variants") or [])
|
||||
if any(re.search(rf"\b{re.escape(w)}\b", t.get("definition") or "", re.I) for w in forms if w):
|
||||
self.add("W2104", tid, "the definition uses the term it defines")
|
||||
# W2105 coined term in an item stem or option
|
||||
coined = {i: t for i, t in self.reg["terms"].items() if t.get("kind") == "coined"}
|
||||
for f, iid, field, text in self.item_text():
|
||||
for i, t in coined.items():
|
||||
for w in [t["term"]] + list(t.get("variants") or []):
|
||||
if text and re.search(rf"\b{re.escape(w)}\b", text, re.I):
|
||||
self.add("W2105", f"{iid} {field}", f"coined term '{w}' ({i}); write '{t.get('exam_wording', 'its textbook name')}'")
|
||||
# W2106 a value with no source
|
||||
for vid, v in self.reg["values"].items():
|
||||
if not v.get("source"):
|
||||
self.add("W2106", vid, "no source")
|
||||
# W2107 a conflicts pattern matches student-facing text or an item
|
||||
pats = [(vid, rx) for vid, v in self.reg["values"].items() for rx in map(safe_re, v.get("conflicts") or []) if rx]
|
||||
for where, field, text in self.prose():
|
||||
for vid, rx in pats:
|
||||
if text and rx.search(text):
|
||||
self.add("W2107", where, f"{field} matches a variant of {vid}; write {{{vid}}}")
|
||||
for f, iid, field, text in self.item_text():
|
||||
for vid, rx in pats:
|
||||
if text and rx.search(text):
|
||||
self.add("W2107", f"{iid} {field}", f"matches a variant of {vid}")
|
||||
# W2108 policy-forbidden words in objective or target text
|
||||
forbid = [rx for rx in (safe_re(p, re.I) for p in self.policy.get("target_text_forbid") or []) if rx]
|
||||
for reg in ("learning_objectives", "learning_targets"):
|
||||
for i, e in self.reg[reg].items():
|
||||
for rx in forbid:
|
||||
if rx.search(e.get("text") or ""):
|
||||
self.add("W2108", i, f"text matches the course's forbidden pattern {rx.pattern!r}")
|
||||
# W2109 an explanation names a term in braces that the target does not list (nor its prerequisite targets)
|
||||
for tid, t in self.reg["learning_targets"].items():
|
||||
listed = set(t.get("terms") or [])
|
||||
for p in t.get("prerequisites") or []:
|
||||
listed |= set((self.reg["learning_targets"].get(p) or {}).get("terms") or [])
|
||||
for m in BRACE.finditer(t.get("explanation") or ""):
|
||||
if m.group(1).startswith("term-") and m.group(1) not in listed:
|
||||
self.add("W2109", tid, f"explanation uses {{{m.group(1)}}}, which the target does not list in terms")
|
||||
# W2110 a recall value printed in an item
|
||||
for vid, v in self.reg["values"].items():
|
||||
if v.get("recall"):
|
||||
for f, iid, field, text in self.item_text():
|
||||
if field in ("stem",) or field.startswith("option"):
|
||||
if text and v.get("say") and v["say"].lower() in text.lower():
|
||||
self.add("W2110", f"{iid} {field}", f"prints recall value {vid}")
|
||||
# W2111 an equation a ceiling-3+ target turns on, with no implications
|
||||
for tid, t in self.reg["learning_targets"].items():
|
||||
if int(t.get("level_ceiling") or 0) >= 3:
|
||||
for eid in t.get("equations") or []:
|
||||
if self.exists("equations", eid) and not self.reg["equations"][eid].get("implications"):
|
||||
self.add("W2111", tid, f"turns on {eid}, which lists no implications to test")
|
||||
# I2112 defined in a file other than the objective whose targets first need it (convention, info)
|
||||
first = self.first_use()
|
||||
for k in GLOSSARY:
|
||||
for i in self.reg[k]:
|
||||
need = first.get(i)
|
||||
if need and self.where[i].startswith("objectives/") and Path(self.where[i]).stem != need[1]:
|
||||
self.add("I2112", i, f"defined in {self.where[i]}; first needed by {need[1]} ({need[0]})")
|
||||
# I2113 proposed entries waiting for approval
|
||||
n = sum(1 for k in GLOSSARY for e in self.reg[k].values() if e.get("status") == "proposed")
|
||||
if n:
|
||||
self.add("I2113", "glossary", f"{n} proposed entr{'y' if n == 1 else 'ies'} waiting for the instructor")
|
||||
return self
|
||||
|
||||
# ------------------------------------------------------------- derivations for the lecture page
|
||||
def lecture_order(self):
|
||||
return sorted(self.lectures, key=lambda l: (str(self.lectures[l].get("date") or ""), l))
|
||||
|
||||
def targets_of(self, lid):
|
||||
objs = self.lectures[lid].get("teaches") or []
|
||||
return [(o, tid, t) for o in objs for tid, t in self.reg["learning_targets"].items() if t.get("objective") == o]
|
||||
|
||||
def first_use(self):
|
||||
"""glossary id -> (lecture, objective) of the first target, in teaching order, that lists it."""
|
||||
first = {}
|
||||
for lid in self.lecture_order():
|
||||
for o, tid, t in self.targets_of(lid):
|
||||
for k in GLOSSARY:
|
||||
for x in t.get(k) or []:
|
||||
first.setdefault(x, (lid, o))
|
||||
return first
|
||||
|
||||
def render(self, text):
|
||||
def sub(m):
|
||||
i = m.group(1)
|
||||
reg = self.kind_of(i)
|
||||
e = self.reg.get(reg, {}).get(i, {})
|
||||
return {"terms": lambda: f"[{e.get('term', i)}]", "equations": lambda: f"[{e.get('name', i)}]",
|
||||
"values": lambda: e.get("say", i), "misconceptions": lambda: f"'{e.get('belief', i)}'",
|
||||
"learning_targets": lambda: f"T {i}", "learning_objectives": lambda: f"O {i}"}.get(reg, lambda: i)()
|
||||
return BRACE.sub(sub, " ".join(str(text or "").split()))
|
||||
|
||||
def page(self, lid):
|
||||
lec, first = self.lectures[lid], self.first_use()
|
||||
levels = self.policy.get("levels") or {}
|
||||
L = [f"# {lid}: {lec.get('title')}", "", self.render(lec.get("description")), ""]
|
||||
rows = self.targets_of(lid)
|
||||
need = {k: [] for k in GLOSSARY}
|
||||
for o in lec.get("teaches") or []:
|
||||
ob = self.reg["learning_objectives"].get(o, {})
|
||||
L += [f"## {self.render(ob.get('text'))}", "", self.render(ob.get("description")), ""]
|
||||
ts = sorted([(int(t.get("level_ceiling") or ob.get("level_ceiling") or 0), tid, t) for oo, tid, t in rows if oo == o])
|
||||
for lv, tid, t in ts:
|
||||
name = (levels.get(str(lv)) or {}).get("name", f"Level {lv}")
|
||||
L.append(f"- **{self.render(t.get('text'))}** ({name})")
|
||||
if t.get("explanation"):
|
||||
L.append(f" {self.render(t['explanation'])}")
|
||||
for k in GLOSSARY:
|
||||
for x in t.get(k) or []:
|
||||
if x not in need[k]:
|
||||
need[k].append(x)
|
||||
L.append("")
|
||||
new_terms = [x for x in need["terms"] if first.get(x, (None,))[0] == lid]
|
||||
old_terms = [x for x in need["terms"] if x not in new_terms]
|
||||
L += ["## New terms", ""]
|
||||
for x in new_terms:
|
||||
t = self.reg["terms"].get(x, {})
|
||||
tb = "; ".join(b["term"] for b in t.get("textbook") or [])
|
||||
L.append(f"- **{t.get('term')}**{(' ' + t['symbol']) if t.get('symbol') else ''}: {self.render(t.get('definition'))}"
|
||||
+ (f" (textbooks: {tb})" if tb and t.get("kind") in ("renamed", "coined") else ""))
|
||||
if old_terms:
|
||||
L += ["", "Terms from earlier lectures: " + ", ".join(
|
||||
f"{self.reg['terms'].get(x, {}).get('term', x)} ({first.get(x, ('?',))[0]})" for x in old_terms)]
|
||||
if need["equations"]:
|
||||
L += ["", "## Equations", ""]
|
||||
for x in need["equations"]:
|
||||
e = self.reg["equations"].get(x, {})
|
||||
L += [f"### {e.get('name')}", "", f"$${e.get('tex')}$$", "", self.render(e.get("says")), ""]
|
||||
for s in e.get("symbols") or []:
|
||||
tm = self.reg["terms"].get(s.get("term") or "", {})
|
||||
L.append(f"- {s['symbol']}: {tm.get('term') or s.get('meaning')}")
|
||||
for imp in e.get("implications") or []:
|
||||
L.append(f"- What it tells you ({imp['form'].replace('_', ' ')}): {self.render(imp['statement'])}")
|
||||
for a in e.get("assumes") or []:
|
||||
L.append(f"- Assumes: {self.render(a)}")
|
||||
for a in e.get("fails_when") or []:
|
||||
L.append(f"- Fails when: {self.render(a)}")
|
||||
L.append("")
|
||||
if need["values"]:
|
||||
L += ["## Numbers to know", ""]
|
||||
for x in need["values"]:
|
||||
v = self.reg["values"].get(x, {})
|
||||
L.append(f"- {v.get('name')}: {v.get('say')}" + (" (know this one)" if v.get("recall") else ""))
|
||||
L.append("")
|
||||
if need["misconceptions"]:
|
||||
L += ["## Common mistakes", ""]
|
||||
for x in need["misconceptions"]:
|
||||
m = self.reg["misconceptions"].get(x, {})
|
||||
L.append(f"- *{self.render(m.get('belief'))}* {self.render(m.get('correction'))}")
|
||||
L.append("")
|
||||
L += ["## Readings", ""]
|
||||
for r in lec.get("readings") or []:
|
||||
if isinstance(r, dict):
|
||||
ref = self.references.get(r["ref"], {})
|
||||
L.append(f"- {ref.get('label', r['ref'])} {r.get('locator', '')}"
|
||||
+ (f" ({r['minutes']} min)" if r.get("minutes") else "") + f": {self.render(r.get('focus'))}")
|
||||
mats = lec.get("materials") or []
|
||||
if mats:
|
||||
L += ["", "## Materials", ""] + [f"- {m.get('title') or m['kind']}: {m['url']}" for m in mats]
|
||||
return "\n".join(L) + "\n"
|
||||
|
||||
|
||||
def selftest(root):
|
||||
"""Break the example once per rule and check the rule fires. The list is the test plan for the Rust port."""
|
||||
import copy
|
||||
base = Course(root)
|
||||
T, R = base.reg["learning_targets"], base.reg
|
||||
|
||||
def run(mut):
|
||||
c = copy.deepcopy(base)
|
||||
c.findings = []
|
||||
mut(c)
|
||||
return {f[0] for f in c.check().lint().findings}
|
||||
|
||||
cases = [
|
||||
("E2102", lambda c: c.reg["learning_targets"]["t-align-fill-matrix"]["terms"].append("term-nope")),
|
||||
("E2103", lambda c: c.reg["equations"]["eq-global-recurrence"]["symbols"].append({"symbol": "q"})),
|
||||
("E2104", lambda c: c.reg["values"]["val-alignment-count-100"].pop("value")),
|
||||
("E2105", lambda c: c.reg["values"]["val-alignment-count-100"]["source"].update(ref="nobody2020")),
|
||||
("E2106", lambda c: c.reg["terms"]["term-gap"].update(definition="See {term-missing}.")),
|
||||
("E2107", lambda c: c.reg["values"]["val-per-decade"]["conflicts"].append("5.7(")),
|
||||
("E2108", lambda c: c.items[0][1]["options"][1].update(misconception_id="mis-nope")),
|
||||
("W2101", lambda c: c.reg["terms"].update({"term-unused": {"term": "unused", "definition": "Not needed."}})),
|
||||
("W2102", lambda c: c.reg["terms"]["term-gap"].update(kind="renamed")),
|
||||
("W2103", lambda c: c.reg["terms"]["term-decade"].pop("exam_wording")),
|
||||
("W2104", lambda c: c.reg["terms"]["term-gap"].update(definition="A gap is a dash.")),
|
||||
("W2105", lambda c: c.items[0][1].update(stem=c.items[0][1]["stem"] + " Think in decades.")),
|
||||
("W2106", lambda c: c.reg["values"]["val-alignment-count-100"].pop("source")),
|
||||
("W2107", lambda c: c.reg["learning_targets"]["t-align-fill-matrix"].update(explanation="It costs 5.7 kJ.")),
|
||||
("W2108", lambda c: c.reg["learning_targets"]["t-align-fill-matrix"].update(text="Calculate the score.")),
|
||||
("W2109", lambda c: c.reg["learning_targets"]["t-align-gap-penalty-effect"].update(
|
||||
explanation="Unlike a {term-local-alignment}, the path changes.")),
|
||||
("W2110", lambda c: c.items[0][1].update(stem="Given about 6 kJ/mol per ten-fold ratio, which is larger?")),
|
||||
("W2111", lambda c: c.reg["equations"]["eq-global-recurrence"].pop("implications")),
|
||||
("I2112", lambda c: c.where.update({"term-gap": "objectives/lo-alignment-recurrence.yaml"})),
|
||||
]
|
||||
bad = 0
|
||||
for code, mut in cases:
|
||||
got = run(mut)
|
||||
ok = code in got
|
||||
bad += not ok
|
||||
print(f" {'ok ' if ok else 'MISS'} {code}" + ("" if ok else f" (got {sorted(got)})"))
|
||||
print(f"{len(cases) - bad} of {len(cases)} rules fire on their broken case")
|
||||
return 1 if bad else 0
|
||||
|
||||
|
||||
def main():
|
||||
ap = argparse.ArgumentParser()
|
||||
ap.add_argument("course")
|
||||
ap.add_argument("--page", help="print the derived lecture page for this lecture id")
|
||||
ap.add_argument("--selftest", action="store_true", help="break the course once per rule and check each fires")
|
||||
a = ap.parse_args()
|
||||
if a.selftest:
|
||||
return selftest(a.course)
|
||||
c = Course(a.course).check().lint()
|
||||
for code, where, msg in sorted(c.findings):
|
||||
print(f" {code} [{where}] {msg}")
|
||||
errs = sum(1 for f in c.findings if f[0].startswith("E"))
|
||||
print(f"{errs} error(s), {sum(1 for f in c.findings if f[0].startswith('W'))} warning(s), "
|
||||
f"{sum(1 for f in c.findings if f[0].startswith('I'))} note(s)")
|
||||
if a.page:
|
||||
print("\n" + c.page(a.page))
|
||||
return 1 if errs else 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -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"
|
||||
}
|
||||
@@ -0,0 +1,594 @@
|
||||
{
|
||||
"$id": "https://coursebank.dev/schema/bank.schema.json",
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"additionalProperties": false,
|
||||
"description": "A collection of items. Split banks by unit or topic; ids must be unique across the whole course, not just within a file.",
|
||||
"properties": {
|
||||
"bank": {
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"description": {
|
||||
"type": "string"
|
||||
},
|
||||
"id": {
|
||||
"description": "Bank id, unique within the course.",
|
||||
"minLength": 1,
|
||||
"type": "string"
|
||||
},
|
||||
"scope": {
|
||||
"additionalProperties": false,
|
||||
"description": "What this bank is meant to cover. Validation warns when an item strays outside it.",
|
||||
"properties": {
|
||||
"learning_targets": {
|
||||
"description": "Target ids.",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"lectures": {
|
||||
"description": "Lecture ids.",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"topics": {
|
||||
"description": "Topics.",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"units": {
|
||||
"description": "Unit ids.",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
}
|
||||
},
|
||||
"type": "object"
|
||||
},
|
||||
"title": {
|
||||
"description": "Human-readable title.",
|
||||
"minLength": 1,
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"id",
|
||||
"title"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"defaults": {
|
||||
"additionalProperties": false,
|
||||
"description": "Applied to every item in the file that does not set the field. Saves repeating yourself; the item always wins.",
|
||||
"properties": {
|
||||
"author": {
|
||||
"type": "string"
|
||||
},
|
||||
"lectures": {
|
||||
"description": "Lecture ids for items with no sources of their own.",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"options_per_item": {
|
||||
"minimum": 2,
|
||||
"type": "integer"
|
||||
},
|
||||
"points": {
|
||||
"exclusiveMinimum": 0.0,
|
||||
"type": "number"
|
||||
},
|
||||
"topics": {
|
||||
"description": "Topics added to every item.",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
}
|
||||
},
|
||||
"type": "object"
|
||||
},
|
||||
"items": {
|
||||
"items": {
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"assets": {
|
||||
"items": {
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"alt": {
|
||||
"description": "Alt text. Required in practice: the linter flags an asset without it, because an exam question a screen reader cannot convey is not answerable.",
|
||||
"type": "string"
|
||||
},
|
||||
"caption": {
|
||||
"type": "string"
|
||||
},
|
||||
"path": {
|
||||
"description": "Path to the image, relative to the course root.",
|
||||
"minLength": 1,
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"path"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"author": {
|
||||
"type": "string"
|
||||
},
|
||||
"bonus": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"cognitive_process": {
|
||||
"description": "The specific cognitive operation. Must belong to the item's level — level 1: recognize, recall; level 2: interpret, exemplify, classify, summarize, infer, compare, explain; level 3: execute, implement; level 4: differentiate, organize, attribute; level 5: check, critique, generate, plan, produce.",
|
||||
"enum": [
|
||||
"recognize",
|
||||
"recall",
|
||||
"interpret",
|
||||
"exemplify",
|
||||
"classify",
|
||||
"summarize",
|
||||
"infer",
|
||||
"compare",
|
||||
"explain",
|
||||
"execute",
|
||||
"implement",
|
||||
"differentiate",
|
||||
"organize",
|
||||
"attribute",
|
||||
"check",
|
||||
"critique",
|
||||
"generate",
|
||||
"plan",
|
||||
"produce"
|
||||
],
|
||||
"type": "string"
|
||||
},
|
||||
"design": {
|
||||
"additionalProperties": false,
|
||||
"description": "What you expected before giving the item. Kept separate from observed statistics so the two can be compared.",
|
||||
"properties": {
|
||||
"expected_difficulty": {
|
||||
"description": "Fraction you expect to answer correctly.",
|
||||
"maximum": 1.0,
|
||||
"minimum": 0.0,
|
||||
"type": "number"
|
||||
},
|
||||
"expected_discrimination": {
|
||||
"enum": [
|
||||
"low",
|
||||
"moderate",
|
||||
"high"
|
||||
],
|
||||
"type": "string"
|
||||
},
|
||||
"expected_time_seconds": {
|
||||
"exclusiveMinimum": 0.0,
|
||||
"type": "number"
|
||||
},
|
||||
"rationale": {
|
||||
"description": "Why this item exists and what it is meant to catch.",
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"type": "object"
|
||||
},
|
||||
"format": {
|
||||
"description": "single_best_answer keys exactly one option; multiple_response keys two or more; open_response takes no options and is graded from its solution.",
|
||||
"enum": [
|
||||
"single_best_answer",
|
||||
"multiple_response",
|
||||
"true_false",
|
||||
"open_response"
|
||||
],
|
||||
"type": "string"
|
||||
},
|
||||
"history": {
|
||||
"description": "One entry per version. Versions must increase.",
|
||||
"items": {
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"author": {
|
||||
"type": "string"
|
||||
},
|
||||
"change": {
|
||||
"description": "What changed and why.",
|
||||
"minLength": 1,
|
||||
"type": "string"
|
||||
},
|
||||
"date": {
|
||||
"description": "When the change was made.",
|
||||
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
|
||||
"type": "string"
|
||||
},
|
||||
"version": {
|
||||
"minimum": 1,
|
||||
"type": "integer"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"version",
|
||||
"date",
|
||||
"change"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"id": {
|
||||
"description": "Item id, e.g. q-glycolysis-rate-limiting-step. Stable forever: assessment records and stored responses refer to it, so renaming one is a migration rather than an edit. A trailing counter is no longer expected — it recorded when the item was written, which git knows — but an id that still has one stays valid.",
|
||||
"pattern": "^q-[a-z0-9]+(-[a-z0-9]+)*$",
|
||||
"type": "string"
|
||||
},
|
||||
"learning_targets": {
|
||||
"description": "Target ids this item measures. Reports aggregate these onto the target's objective, so an item with none contributes to nothing. Name the target rather than the objective: the objective follows from it, and recording which target was asked about is what lets a report explain a result instead of only stating it.",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"level": {
|
||||
"description": "Cognitive level. 1 = Remember (recalling terms, facts, and definitions); 2 = Understand (explaining ideas in your own words); 3 = Apply (using a procedure in a new situation); 4 = Analyze (taking a situation apart and relating the pieces); 5 = Evaluate/Create (judging alternatives or building something new)",
|
||||
"maximum": 5,
|
||||
"minimum": 1,
|
||||
"type": "integer"
|
||||
},
|
||||
"notes_private": {
|
||||
"description": "Never exported anywhere a student can see.",
|
||||
"type": "string"
|
||||
},
|
||||
"options": {
|
||||
"description": "Absent for an open_response item; at least two for any choice format.",
|
||||
"items": {
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"correct": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"credit": {
|
||||
"description": "Partial credit. Requires defensible: true and a defense.",
|
||||
"maximum": 1.0,
|
||||
"minimum": 0.0,
|
||||
"type": "number"
|
||||
},
|
||||
"defense": {
|
||||
"description": "The argument for that reading. Required when defensible is true.",
|
||||
"type": "string"
|
||||
},
|
||||
"defensible": {
|
||||
"description": "This option has a reading under which it is arguably correct. Required before granting partial credit.",
|
||||
"type": "boolean"
|
||||
},
|
||||
"error_type": {
|
||||
"description": "What kind of mistake this distractor is designed to catch. recall_confusion — confused with a neighboring fact; terminology_swap — swapped similar terms; misconception — specific wrong model; incomplete_understanding — partial grasp of the idea; overgeneralization — applied a rule outside its scope; plausible_irrelevant — true but not what was asked; dropped_step — skipped a step; reversed_relationship — reversed the direction; wrong_procedure — used the wrong procedure; sign_or_magnitude_error — sign or magnitude slip; ignores_interacting_condition — ignored an interacting condition; correct_but_incomplete — correct but not best; common_shortcut — took a familiar shortcut",
|
||||
"enum": [
|
||||
"recall_confusion",
|
||||
"terminology_swap",
|
||||
"misconception",
|
||||
"incomplete_understanding",
|
||||
"overgeneralization",
|
||||
"plausible_irrelevant",
|
||||
"dropped_step",
|
||||
"reversed_relationship",
|
||||
"wrong_procedure",
|
||||
"sign_or_magnitude_error",
|
||||
"ignores_interacting_condition",
|
||||
"correct_but_incomplete",
|
||||
"common_shortcut"
|
||||
],
|
||||
"type": "string"
|
||||
},
|
||||
"explanation": {
|
||||
"description": "Why this option is right or wrong. For you, not the student.",
|
||||
"type": "string"
|
||||
},
|
||||
"feedback_student": {
|
||||
"description": "Shown to a student who chose this, on Canvas and in reports.",
|
||||
"type": "string"
|
||||
},
|
||||
"hint": {
|
||||
"type": "string"
|
||||
},
|
||||
"id": {
|
||||
"description": "Option id, unique within the item: `o-fourth-line`. An identity, not a print position — shuffled forms relabel on the way out. A single letter A-H is the pre-2.0 form; `coursebank migrate options` renames it.",
|
||||
"pattern": "^(o-[a-z0-9]+(-[a-z0-9]+)*|[A-H])$",
|
||||
"type": "string"
|
||||
},
|
||||
"misconception": {
|
||||
"description": "The specific wrong belief that leads here. This text is what student reports use, so write it as a completion of 'students pick this when ...'.",
|
||||
"type": "string"
|
||||
},
|
||||
"retired": {
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"on": {
|
||||
"description": "Retirement date.",
|
||||
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
|
||||
"type": "string"
|
||||
},
|
||||
"reason": {
|
||||
"description": "Why it was retired.",
|
||||
"minLength": 1,
|
||||
"type": "string"
|
||||
},
|
||||
"replaced_by": {
|
||||
"description": "Successor item id.",
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"on",
|
||||
"reason"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"selection_rate_expected": {
|
||||
"description": "How often you expect this to be chosen. Compared against reality.",
|
||||
"maximum": 1.0,
|
||||
"minimum": 0.0,
|
||||
"type": "number"
|
||||
},
|
||||
"text": {
|
||||
"description": "The option as a student reads it.",
|
||||
"minLength": 1,
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"id",
|
||||
"text"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"maxItems": 8,
|
||||
"minItems": 2,
|
||||
"type": "array"
|
||||
},
|
||||
"points": {
|
||||
"exclusiveMinimum": 0.0,
|
||||
"type": "number"
|
||||
},
|
||||
"prerequisites": {
|
||||
"description": "Objective ids a student needs before this item.",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"retired": {
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"on": {
|
||||
"description": "Retirement date.",
|
||||
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
|
||||
"type": "string"
|
||||
},
|
||||
"reason": {
|
||||
"description": "Why it was retired.",
|
||||
"minLength": 1,
|
||||
"type": "string"
|
||||
},
|
||||
"replaced_by": {
|
||||
"description": "Successor item id.",
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"on",
|
||||
"reason"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"review": {
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"action": {
|
||||
"enum": [
|
||||
"keep",
|
||||
"revise",
|
||||
"award_partial_credit",
|
||||
"correct_key",
|
||||
"retire",
|
||||
"monitor"
|
||||
],
|
||||
"type": "string"
|
||||
},
|
||||
"notes": {
|
||||
"type": "string"
|
||||
},
|
||||
"reviewed_by": {
|
||||
"type": "string"
|
||||
},
|
||||
"reviewed_on": {
|
||||
"description": "Review date.",
|
||||
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"type": "object"
|
||||
},
|
||||
"solution": {
|
||||
"additionalProperties": false,
|
||||
"description": "The answer, the reasoning, and the rubric. Rendered in the solutions document and the answer key, never in a question paper.",
|
||||
"properties": {
|
||||
"accepted": {
|
||||
"description": "Responses a short constructed answer is accepted as.",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"explanation": {
|
||||
"description": "The worked reasoning a student learns from. The body of the solutions entry.",
|
||||
"type": "string"
|
||||
},
|
||||
"model_answer": {
|
||||
"description": "For an open-response item, the response a full-credit student writes; for a choice item, an optional one-line statement of the key.",
|
||||
"type": "string"
|
||||
},
|
||||
"review": {
|
||||
"description": "Where to look again after missing this item.",
|
||||
"items": {
|
||||
"oneOf": [
|
||||
{
|
||||
"description": "A citation, unparsed.",
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"locator": {
|
||||
"description": "Where inside the work: §6.1, pp. 4-9.",
|
||||
"type": "string"
|
||||
},
|
||||
"path": {
|
||||
"description": "Joined to the reference base_url.",
|
||||
"type": "string"
|
||||
},
|
||||
"ref": {
|
||||
"description": "Citation key into `references`.",
|
||||
"minLength": 1,
|
||||
"type": "string"
|
||||
},
|
||||
"text": {
|
||||
"type": "string"
|
||||
},
|
||||
"url": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"type": "object"
|
||||
}
|
||||
]
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"rubric": {
|
||||
"items": {
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"description": {
|
||||
"description": "What earns the points on this line.",
|
||||
"minLength": 1,
|
||||
"type": "string"
|
||||
},
|
||||
"points": {
|
||||
"minimum": 0.0,
|
||||
"type": "number"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"description"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"type": "array"
|
||||
}
|
||||
},
|
||||
"type": "object"
|
||||
},
|
||||
"sources": {
|
||||
"description": "Where the material was taught. Drives the 'review this' lines in student reports.",
|
||||
"items": {
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"lecture": {
|
||||
"description": "Lecture id from course.yaml.",
|
||||
"minLength": 1,
|
||||
"type": "string"
|
||||
},
|
||||
"readings": {
|
||||
"description": "Specific readings.",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"recording_seconds": {
|
||||
"minimum": 0,
|
||||
"type": "integer"
|
||||
},
|
||||
"slides": {
|
||||
"items": {
|
||||
"minimum": 1,
|
||||
"type": "integer"
|
||||
},
|
||||
"type": "array"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"lecture"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"status": {
|
||||
"description": "Only approved items can be drawn into an assessment.",
|
||||
"enum": [
|
||||
"draft",
|
||||
"in_review",
|
||||
"needs_revision",
|
||||
"approved",
|
||||
"retired"
|
||||
],
|
||||
"type": "string"
|
||||
},
|
||||
"stem": {
|
||||
"description": "The question. Ask something specific; the linter flags stems with no task in them.",
|
||||
"minLength": 1,
|
||||
"type": "string"
|
||||
},
|
||||
"stimulus": {
|
||||
"description": "Stimulus id from course.yaml.",
|
||||
"type": "string"
|
||||
},
|
||||
"title": {
|
||||
"description": "Short internal label. Never shown to students.",
|
||||
"type": "string"
|
||||
},
|
||||
"topics": {
|
||||
"description": "Free-form topics, used for blueprint filtering.",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"version": {
|
||||
"description": "Bump when you change what a student sees. Recorded on every administration so drift is detectable.",
|
||||
"minimum": 1,
|
||||
"type": "integer"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"id",
|
||||
"level",
|
||||
"stem"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"schema_version": {
|
||||
"type": [
|
||||
"string",
|
||||
"number"
|
||||
]
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"bank",
|
||||
"items"
|
||||
],
|
||||
"title": "coursebank item bank",
|
||||
"type": "object"
|
||||
}
|
||||
@@ -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"
|
||||
}
|
||||
@@ -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"
|
||||
}
|
||||
@@ -0,0 +1,131 @@
|
||||
{
|
||||
"$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"
|
||||
},
|
||||
"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": "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,161 @@
|
||||
{
|
||||
"$id": "https://coursebank.dev/schema/objective.schema.json",
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"additionalProperties": false,
|
||||
"description": "One learning objective and the learning targets it decomposes into. A fragment of the course file, merged on load.",
|
||||
"properties": {
|
||||
"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": "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"
|
||||
},
|
||||
"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": "The targets of this file's objective, by id. A target with no `lectures` of its own inherits its objective's.",
|
||||
"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"
|
||||
}
|
||||
},
|
||||
"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.0. Declared in course.yaml; fragments inherit it.",
|
||||
"type": [
|
||||
"string",
|
||||
"number"
|
||||
]
|
||||
}
|
||||
},
|
||||
"title": "coursebank references file",
|
||||
"type": "object"
|
||||
}
|
||||
@@ -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"
|
||||
}
|
||||
@@ -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"
|
||||
}
|
||||
@@ -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"
|
||||
}
|
||||
Reference in new issue
Block a user