Learning Content Format (LCF)

Status: Draft / pre-1.0 · This repo: specification + schema first, libraries later.

A single, open file format for authoring learning content of any subject — languages, mathematics, chemistry, history, music, programming — as plain Markdown files that are human-authorable, git-friendly, and machine-scorable.

LCF is a domain-agnostic core plus extensions that add subject- or format-specific blocks, rendering, and grading. A subject bundle (language, math, chemistry) is a domain extension — a.k.a. a domain pack; a cross-cutting capability (diagram rendering, runnable code, audio) is a utility extension. The core covers ~90% of authoring needs; extensions cover the rest without bloating the core or forking the format. See extensions/.

Why

Learning content is best kept as Markdown files (the source of truth) with a thin database for per-user state. But subject-specific blocks (translation drills, conjugation tables) are hard to generalise, questions typically have no stable identity, and there is no shared notion of formulas, numeric answers, or subject-specific grading. LCF addresses those gaps in one format that stays human-authorable.

Design goals

1. Human-first authoring. A teacher can write and diff a file by hand. No build step to read it.
2. One file = one document. YAML front-matter + a Markdown body. Plain .md.
3. Domain-agnostic core. The core knows about questions, scoring, and structure — never about verbs or valence electrons.
4. Everything else is an extension. Subjects (language, math, chemistry) ship as domain extensions; cross-cutting capabilities (diagrams, runnable code) as utility extensions. Each is a versioned manifest registering new blocks, metadata, checkers, and renderers.
5. Stable question identity. Every interactive element has an id so a quiz engine, analytics pipeline, or spaced-repetition scheduler can track it across edits.
6. Formulas are first-class. LaTeX math and chemistry notation render and grade (numeric tolerance, symbolic equivalence, balanced equations).
7. Graceful degradation. An unknown block still shows its prompt. Old readers don't choke on new packs.
8. Files are the source of truth. Databases hold only per-user state (attempts, SRS, mastery) + a derived index.

What's decided (project charter)

These framing decisions are settled; the specification builds on them:

Decision	Choice
Authoring model	Evolve Markdown + shortcodes (not a structured JSON canonical form)
Domain scope	Domain-agnostic core; language/math/chemistry as packs
Standards	Greenfield, borrowing ideas from QTI 3.0, H5P, xAPI/cmi5 (mappings are a non-normative appendix)
First deliverable	Written spec + JSON Schema, before library code
File extension	.lcf.md (valid Markdown to generic tools, unambiguous to LCF tooling)
Licence	MIT (see LICENSE) — an open, shared format

The remaining design questions (kind set, composite vs group, pack distribution, governance) are now resolved in docs/ROADMAP.md § Resolved decisions.

Documents in this repo

File	What it is
docs/SPECIFICATION.md	The core LCF specification (draft v0.1) — document model, blocks, interactions, scoring, identity, extension.
docs/DOMAIN-PACKS.md	How domain packs extend the core, with Language / Math / Chemistry sketches. Generalised by extensions/.
extensions/	The extension system: umbrella guide + reference extensions (music, mermaid, code).
docs/INTEROP.md	Non-normative mappings to QTI 3.0, H5P, and xAPI/cmi5.
docs/ROADMAP.md	Phased plan from spec → schema → reference libraries → adoption.
schema/core.schema.json	Starter JSON Schema for front-matter + block envelopes.
schema/extension.schema.json	JSON Schema for an extension manifest (extension.yaml).
examples/	Cross-domain sample .lcf.md documents (language, math, chemistry, generic quiz).
LICENSE	MIT licence for the spec, schema, and reference libraries.

Status & next step

This is a first draft for discussion, not a frozen standard. The immediate next step (see the roadmap) is to review the core spec, lock the front-matter and core-interaction vocabulary, then formalise the JSON Schema and write conformance fixtures — before writing any parser.

Licence

MIT — © 2026 Ortic Solutions GmbH. See LICENSE.