projects / easemysemester / features
The content contract
A strict, deterministic markdown format and parser that makes ten years of hand curated exam questions machine verifiable before any analytics feature can trust them.
feature · current · updated 2026-09-15 · EaseMySemester case study
See overview.
The admin imports canonical markdown files. One file is one exam, subject and paper unit.
YAML frontmatter is authoritative; the filename is only a hint. The body allows a fixed set
of headings, and every question's first line ends with a five token tag: board, year, month,
session, paper, for example (AKU 2020 null Reg P1). Repeat appearances join inside one
parenthesis.
The parser is a gate
It rejects, with a line numbered report, missing or invalid frontmatter, a heading outside
the allowed set, a question without a tag, a malformed tag, a null where one is not
allowed, a tag whose paper contradicts the frontmatter, an empty type heading, or a question
tagged for both papers. Nothing is silently corrected.
Publish is idempotent: it replaces all questions for a unit, so re uploading a corrected file is safe. A later additive merge mode matches existing questions by normalised body, type and chapter, and appends new occurrences instead of replacing.
How the source markdown gets written
A fixed prompt run once per exam, subject and paper in NotebookLM generates the canonical file: exact frontmatter, the allowed heading set only, one numbered item per question with its five token tag, and repeat appearances merged into one tag list. The prompt is versioned alongside the parser it feeds, since a change to one has to track the other.
The five token tag replaced an earlier, free form year tag in v2: the parser stopped storing a free form year string and a minimum year, each appearance became its own occurrence row, and paper moved onto the question. Each token is validated on its own grammar, board, year, month, session, paper, and a tag's paper must match the file's own frontmatter paper or the file is rejected.
Why this is a product decision
Every downstream feature, browse, analytics and eventually retrieval, inherits its quality from this contract. Making the correctness of the source of truth a product feature, before any of the smart features existed, is what made the later work cheap.