Lesson bundle format
A Studium lesson is one JSON file, lesson.json, usually in its own folder with the media it refers
to. Every surface (MCP server, VS Code pane, HTTP servers, teacher dashboard) reads the same format.
This page describes it field by field; the tables are generated from the Zod schemas in
packages/lesson-bundle-schema, which are the
reference. A Pydantic mirror for the Python services lives in
packages/lesson-bundle-schema/python/.
To write a lesson, start from Author a lesson or let an assistant build one with the authoring tools. What each scene type asks of the learner is explained in Scene types.
A bundle on disk
my-course/
lesson.json the bundle (this format)
approval.json written by `experience_packet.py approve`, bound to the exact bytes of lesson.json
media/... files that render_assets or image_path point to, relative to the folder
A bundle_ref (the argument of start_lesson_session) is a path relative to the lessons folder: a
lesson.json, its folder, or a .zip bundle. Lessons built by an assistant land in the learner's
library, <STUDIUM_HOME>/library (see Configuration). Working examples:
fixtures/capsule-run-demo/lesson.json (two scenes) and
fixtures/atomistique-l1/lesson.json (a full course).
Check a bundle
# Schema: exit 0 and "OK <file>: N scenes" when the file parses
node_modules/.pnpm/node_modules/.bin/tsx tools/bundle_validate.ts path/to/lesson.json
# Teaching-material lint: ERROR findings fail, WARN and INFO do not
node tools/bundle_lint.mjs path/to/lesson.json
The linter goes beyond the schema: a quiz needs exactly one correct choice, an unfilled TODO
placeholder is an error, graph relations and asset kinds must be known ones, and self-study bundles
get findings about who wrote the key. Both commands are described in the CLI reference.
Who wrote it, and who checked it
metadata.authoring tells every surface how to present the lesson honestly:
| Field | Values | Meaning |
|---|---|---|
mode |
teacher, self_study |
A teacher's lesson, or one the learner (or their assistant) made from references they chose. |
drafted_by |
agent, learner, teacher |
Who wrote the content and its answer keys. An agent draft opens with a notice that an AI drafted it from the learner's sources and no teacher checked it. |
author_is_learner |
true, false |
The person who answers also wrote the lesson. |
learner_profile |
{minutes_per_day?, target_date?} |
The learner's minutes a day (1 to 600) and target date, kept by create_lesson; the study plan sizes the next step with the minutes. What the learner said they know or like is never stored here. |
Two more fields carry provenance. A scene marked diagnostic: true is an opening question on what the
learner already knows: it is played once and never chosen for a review. A citation in
evidence.bibliographic_refs[] can carry the source's license, which surfaces show after its title.
A bundle without metadata.authoring (older bundles) is read as a teacher's lesson. validated_by
and validated_at record the teacher's review; experience_packet.py approve sets them and writes
approval.json with the SHA-256 of the final bytes, so any later edit shows as unapproved. Only
that record makes a lesson read as validated: validated_by text alone shows as "no approval
recorded". A self-study bundle cannot be approved.
Field reference
Schema version: 1.4. Field tables are generated from the Zod schemas; rules that span several fields (weights that sum to 1, ids that must exist) are checked by the schema and the linter but do not appear here.
Bundle
| Field | Type | Required | Description |
|---|---|---|---|
schema_version |
1.4 |
yes | |
bundle_id |
string | yes | |
source_plan_id |
string | yes | |
metadata |
object | yes | See Metadata. |
concepts |
array of objects, at least 1 item | yes | See Concept. |
scenes |
array of objects of 13 shapes, at least 1 item | yes | See Scene types. |
rules |
array of objects | yes | See Adaptation rule. |
validated_by |
string (at least 3 chars) | yes | |
validated_at |
string, date-time | yes | |
assessment_blueprint |
object | no | See Assessment blueprint. |
learning_workflow_graph |
object or null | no | |
universes |
object or null | no |
Metadata
| Field | Type | Required | Description |
|---|---|---|---|
title |
string | yes | |
target |
string | yes | |
duration_minutes |
integer (> 0) | yes | |
language |
string (at least 2 chars) | yes | |
discipline |
string | yes | |
authoring |
object | no | |
authoring.mode |
one of teacher, self_study |
yes | |
authoring.author_is_learner |
boolean | no | Default false. |
authoring.drafted_by |
one of agent, learner, teacher |
no | |
authoring.note |
string | no | |
authoring.learner_profile |
object | no |
Concept
| Field | Type | Required |
|---|---|---|
id |
string | yes |
title |
string | yes |
description |
string | yes |
bloom_level_target |
one of remember, understand, apply, analyze, evaluate, create |
yes |
Scene fields
Every scene, whatever its type, has these fields.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string (non-empty) | yes | |
type |
one of intro, concept, quiz, meta_checkpoint, reproduction, ai_critique, discussion, spot_the_flaw, explain_back, comparison, summary_audit, prompt_practice, communication_sim |
yes | |
title |
string (non-empty) | yes | |
objective_refs |
array of string | yes | |
concept_refs |
array of string | yes | |
estimated_seconds |
integer (≥ 0) | yes | |
adaptation_hooks |
array of string | yes | |
render_assets |
array of objects | no | See Render asset. |
evidence |
object | no | See Evidence. |
diagnostic |
boolean | no |
Scene types
13 types. Each table lists the fields a type adds to the scene fields.
intro
| Field | Type | Required |
|---|---|---|
markdown |
string | yes |
concept
| Field | Type | Required |
|---|---|---|
markdown |
string | yes |
image_path |
string | no |
quiz
| Field | Type | Required |
|---|---|---|
question |
string | yes |
choices |
array of objects, 2–6 items | yes |
choices[].id |
string | yes |
choices[].text |
string | yes |
choices[].correct |
boolean | yes |
feedback_correct |
string | yes |
feedback_incorrect |
string | yes |
hints |
array of string | yes |
meta_checkpoint
| Field | Type | Required |
|---|---|---|
pre_question |
string | yes |
post_question |
string | yes |
scale_labels |
array of string, 5 items | yes |
reproduction
| Field | Type | Required |
|---|---|---|
task_card_id |
string | yes |
steps |
array of objects, at least 1 item | yes |
steps[].step_id |
string | yes |
steps[].instruction |
string | yes |
steps[].expected_input_schema |
object (free form) | yes |
steps[].expected_output |
string or object (free form) | yes |
prov_derived_from |
string, uri | no |
image_path |
string | no |
reference_result |
object | no |
reference_result.ran |
boolean | yes |
reference_result.passed |
boolean | yes |
reference_result.landmark |
string or null | yes |
reference_result.figure_path |
string or null | yes |
reference_result.checks |
array of objects | yes |
reference_result.checks[].check |
string | yes |
reference_result.checks[].passed |
boolean | yes |
reference_result.provenance |
object | yes |
reference_result.provenance.capsule_doi |
string or null | yes |
reference_result.provenance.cmd |
array of string | yes |
reference_result.provenance.env |
string | yes |
run_manifest |
object | no |
run_manifest.capsule_ref |
string (non-empty) | yes |
run_manifest.cmd |
array of string, at least 1 item | yes |
run_manifest.working_dir |
string or null | no |
run_manifest.timeout_s |
number (> 0) | no |
run_manifest.requirements |
array of string | no |
run_manifest.expected_outputs |
array of string | yes |
run_manifest.verify_checks |
array of string | yes |
run_manifest.research_question |
string | no |
run_manifest.landmark_pattern |
string | no |
ai_critique
| Field | Type | Required |
|---|---|---|
claims |
array of objects, 1–3 items | yes |
claims[].id |
string | yes |
claims[].text |
string | yes |
claims[].flaws_expected |
array of string | yes |
rubric |
object | yes |
rubric.completeness |
number (0–1) | yes |
rubric.evidence_quality |
number (0–1) | yes |
rubric.tone |
number (0–1) | yes |
discussion
| Field | Type | Required |
|---|---|---|
topic |
string (non-empty) | yes |
seed_claim |
string (non-empty) | yes |
target_signals |
array of one of justification, hypothesis, question, counterexample, synthesis, at least 1 item |
yes |
max_turns |
integer (> 0) | yes |
spot_the_flaw
| Field | Type | Required |
|---|---|---|
flawed_content |
string (non-empty) | yes |
claims |
array of objects, 1–5 items | yes |
claims[].id |
string | yes |
claims[].text |
string | yes |
claims[].flaws_expected |
array of string, at least 1 item | yes |
model_correction |
string (non-empty) | yes |
rubric |
object | yes |
rubric.completeness |
number (0–1) | yes |
rubric.evidence_quality |
number (0–1) | yes |
rubric.tone |
number (0–1) | yes |
reference_result |
object | no |
reference_result.ran |
boolean | yes |
reference_result.passed |
boolean | yes |
reference_result.landmark |
string or null | yes |
reference_result.figure_path |
string or null | yes |
reference_result.checks |
array of objects | yes |
reference_result.checks[].check |
string | yes |
reference_result.checks[].passed |
boolean | yes |
reference_result.provenance |
object | yes |
reference_result.provenance.capsule_doi |
string or null | yes |
reference_result.provenance.cmd |
array of string | yes |
reference_result.provenance.env |
string | yes |
sound_claims |
array of objects | no |
sound_claims[].id |
string | yes |
sound_claims[].text |
string | yes |
reference_from_run |
string | no |
regenerate_from_run |
boolean | no |
verdict_deck |
boolean | no |
explain_back
| Field | Type | Required |
|---|---|---|
prompt |
string (non-empty) | yes |
key_points |
array of objects, 1–6 items | yes |
key_points[].id |
string | yes |
key_points[].text |
string | yes |
key_points[].cues |
array of string, at least 1 item | yes |
model_explanation |
string (non-empty) | yes |
rubric |
object | yes |
rubric.completeness |
number (0–1) | yes |
rubric.evidence_quality |
number (0–1) | yes |
rubric.tone |
number (0–1) | yes |
comparison
| Field | Type | Required |
|---|---|---|
prompt |
string (non-empty) | yes |
artifact_a |
string (non-empty) | yes |
artifact_b |
string (non-empty) | yes |
key_points |
array of objects, at least 1 item | yes |
key_points[].id |
string | yes |
key_points[].text |
string | yes |
key_points[].cues |
array of string, at least 1 item | yes |
model_answer |
string (non-empty) | yes |
rubric |
object | yes |
rubric.completeness |
number (0–1) | yes |
rubric.evidence_quality |
number (0–1) | yes |
rubric.tone |
number (0–1) | yes |
summary_audit
| Field | Type | Required |
|---|---|---|
source_content |
string (non-empty) | yes |
ai_summary |
string (non-empty) | yes |
claims |
array of objects, 1–5 items | yes |
claims[].id |
string | yes |
claims[].text |
string | yes |
claims[].flaws_expected |
array of string, at least 1 item | yes |
model_correction |
string (non-empty) | yes |
rubric |
object | yes |
rubric.completeness |
number (0–1) | yes |
rubric.evidence_quality |
number (0–1) | yes |
rubric.tone |
number (0–1) | yes |
prompt_practice
| Field | Type | Required |
|---|---|---|
task |
string (non-empty) | yes |
starter_prompt |
string | no |
key_points |
array of objects, at least 1 item | yes |
key_points[].id |
string | yes |
key_points[].text |
string | yes |
key_points[].cues |
array of string, at least 1 item | yes |
model_prompt |
string (non-empty) | yes |
rubric |
object | yes |
rubric.completeness |
number (0–1) | yes |
rubric.evidence_quality |
number (0–1) | yes |
rubric.tone |
number (0–1) | yes |
communication_sim
| Field | Type | Required |
|---|---|---|
scenario |
string (non-empty) | yes |
prompt |
string (non-empty) | yes |
key_points |
array of objects, at least 1 item | yes |
key_points[].id |
string | yes |
key_points[].text |
string | yes |
key_points[].cues |
array of string, at least 1 item | yes |
model_response |
string (non-empty) | yes |
rubric |
object | yes |
rubric.completeness |
number (0–1) | yes |
rubric.evidence_quality |
number (0–1) | yes |
rubric.tone |
number (0–1) | yes |
Adaptation rule
| Field | Type | Required |
|---|---|---|
id |
string | yes |
when |
map of string | yes |
action |
object, one of 5 shapes | yes |
action.kind |
one of advance_to_next_scene, replay_current_scene, skip_to_next_concept, show_calibration_panel, show_explanation_panel |
yes |
action.reason |
string | in replay_current_scene |
modulator |
one of M1, M3, M6 |
yes |
explanation_short |
string | yes |
Render asset
| Field | Type | Required |
|---|---|---|
kind |
one of image, audio, video, svg, equation_latex, plot_spec, code, data_csv, protocol_md, executed_result, orbital, mol_3d, spectrum |
yes |
title |
string | no |
payload |
string | no |
path |
string | no |
language |
string | no |
format |
string | no |
provenance |
string | no |
meta |
object (free form) | no |
legend |
array of objects, at least 1 item | no |
legend[].symbol |
string | yes |
legend[].meaning |
string | yes |
Evidence
| Field | Type | Required |
|---|---|---|
bibliographic_refs |
array of objects | no |
bibliographic_refs[].perspicacite_doc_id |
string (non-empty) | yes |
bibliographic_refs[].doi |
string | no |
bibliographic_refs[].title |
string (non-empty) | yes |
bibliographic_refs[].authors |
array of string | yes |
bibliographic_refs[].year |
integer | no |
bibliographic_refs[].excerpt |
string (≤ 500 chars) | yes |
bibliographic_refs[].relevance_score |
number (0–1) | yes |
bibliographic_refs[].prov_derived_from |
string (non-empty) | yes |
bibliographic_refs[].license |
string (non-empty) | no |
case_studies |
array of objects | no |
case_studies[].title |
string (non-empty) | yes |
case_studies[].summary |
string (≤ 1000 chars) | yes |
case_studies[].source_refs |
array of string | yes |
abs_asset |
object | no |
abs_asset.asset_type |
one of spectrum_viewer_svg, code_snippet, data_csv, protocol_card_md, script_snippet, plot_spec, equation_latex, orbital_viewer_3d, molecule_3d, spectrum_data |
yes |
abs_asset.payload_inline |
string | no |
abs_asset.payload_path |
string | no |
abs_asset.abs_task_card_id |
string | no |
abs_asset.prov_derived_from |
string (non-empty) | yes |
abs_asset.legend |
array of objects, at least 1 item | no |
abs_asset.legend[].symbol |
string | yes |
abs_asset.legend[].meaning |
string | yes |
enrichment_metadata |
object | yes |
enrichment_metadata.enricher_version |
string (non-empty) | yes |
enrichment_metadata.perspicacite_mode_used |
one of basic, advanced, profound, agentic, passages |
yes |
enrichment_metadata.timestamp |
string (non-empty) | yes |
enrichment_metadata.degraded |
boolean | yes |
Assessment blueprint
| Field | Type | Required |
|---|---|---|
dimensions |
array of objects, at least 1 item | yes |
dimensions[].id |
string (non-empty) | yes |
dimensions[].label |
string (non-empty) | yes |
dimensions[].weight |
number (0–1) | yes |
dimensions[].metrics |
array of objects, at least 1 item | yes |
dimensions[].metrics[].endpoint |
one of progress, calibration, autonomy, ai_literacy, reasoning, ai_audit |
yes |
dimensions[].metrics[].field |
string (non-empty) | yes |
dimensions[].metrics[].weight_in_dimension |
number (0–1) | yes |
Keep this page current
pnpm docs:gen # rewrite the generated sections from the schemas
pnpm docs:check # fails when a generated section no longer matches the code