AUTHORING + INTERCHANGE CONTRACT · SCHEMA VERSION 3
A lesson is an ordered set of semantic learning scenes, typed evidence and assessment artifacts, and inspectable local media. Screen layout is derived; the reviewed source remains portable.
One reviewed source. Several faithful views.
Constrained MyST-compatible Markdown carries teaching prose. JSON carries identity, sequence, objectives, assessment logic, claims, sources, glossary, and provenance.
lesson.jsoncontent/*.mdValidated directives become trusted semantic templates. TeX and \ce{...} compile to MathML; diagram JSON and sanitized SVG remain non-executable.
The SPA presents book-like scenes and stable navigation. The same semantics can reflow for narrow screens, assistive technology, print, and future exports.
Everything a reviewer needs travels with the lesson.
The manifest is the table of contents. Scene filenames aid humans; stable scene IDs and array order govern links, corrections, assessment mappings, and rendering.
lesson.json: identity, graph outcomes, objectives, ordered scenes, duration, rights, authorship, and agent provenance.content/*.md: one bounded instructional purpose per scene, with no front matter, raw HTML, JavaScript, or executable plugin.assessment.json: outcome-aligned prompts, answer reasoning, feedback, rubric, retakes, and recovery.references.json, including scope, uncertainty, and review state.glossary.json gives stable definitions, symbols, aliases, and scene references.ATTRIBUTION.md, independent reviews, and separate adjudication.json travel with the lesson.Purpose defines a scene. Pixels do not.
orientation and diagnostic establish relevance, boundaries, prerequisites, and recovery routes.
concept, definition, derivation, and investigation make reasoning explicit.
worked-example exposes representation, decisions, execution, checks, and interpretation.
retrieval-check, misconception, and practice provide feedback without one-shot penalties.
transfer, synthesis, assessment, and references connect mastery to the wider graph.
Equations are source. Images carry meaning.
Constrained TeX remains copyable source. Display math uses an {equation} directive; chemistry uses \ce{...}. The current build produces accessible MathML and rejects file, macro, HTML, link, and resource-loading commands.
Format v1 uses schema-valid *.diagram.json for bounded processes and relationships. Mermaid, DOT, and Vega-Lite may become generated adapters only after validators and deterministic renderers exist.
Sanitized local SVG or raster assets include provenance, meaningful alt text, and a long description when relationships cannot fit in a short alternative. Color and position never carry the only meaning.
Clarity builds a model. Practice makes it usable.
Define outcomes, prerequisites, the target explanatory model, likely learner ideas, mastery evidence, and recovery route before drafting polished prose.
Use coherent causal or relational prose, stable terminology, relevant evidence, explicit assumptions, and connected representations. Difficult ideas stay difficult; hidden inference gaps do not.
Worked examples reveal representation, model selection, plan, reasons, checks, and interpretation. Completion problems then fade support toward independence.
Learners recall, explain, predict, compare, calculate, or construct before feedback. High-value knowledge returns after a delay and in changed contexts.
Contrasting cases expose boundaries, evidenced misconceptions receive refutation and a replacement model, and transfer requires selection or adaptation—not changed numbers alone.
Accuracy, accessibility, rights, and deterministic validation are gates. Completion, readability scores, interaction count, model agreement, and agent self-review are not evidence that students learned.
Authoritative writing contract: read the complete Learning-Content Standard v1. Its dated evidence synthesis distinguishes robust defaults from conditional findings; Lesson Format v1 remains the separate storage and rendering contract.
Accessible by design. Untrusted by default.
Desktop navigation stays fixed while a semantic scene owns bounded overflow. Mobile, zoomed, print, and assistive layouts may reflow normally; authors never encode viewport dimensions.
Raw active content, remote embeds, executable notebooks, path escape, unsafe SVG, and contributor-controlled build code are rejected. Validation never executes lesson code.
A valid standard pack remains a candidate until two isolated reviews inform one fresh finalization and adjudication. The specimen below never counts toward published coverage.
Authors independently synthesize facts instead of closely paraphrasing sources. Any quotation, adaptation, media, or dataset reuse needs a compatible recorded rights basis; agents must honor source-specific access terms. Read the source and reuse policy.
examples/lesson-pack/ and is validated separately from production.