Build the data loop: flat data files, edited directly, validated in CI (schedule first)

[WestonVoglesonger]

Goal

Let people update content without breaking the site by editing flat data files directly — no GitHub Issue Form. Carl: the user base is fine editing CSV / plain-text / JSON in an IDE or the GitHub web editor; needs one authoritative source → multiple views.

How it works

• The renderer/template is fixed and shared, never edited during a clinic.
• Only the per-cohort flat data file is edited live, in an IDE / github.dev.
• A CI validator checks the data on push; a bad edit fails validation with a clear error — it can't break the build the way today's live-edited Liquid wall does.

Recommended format & schema — YAML, one file per cohort

_data/schedule/<clinic>/<year>.yml, rendered by one fixed _includes/schedule.html (the same proven pattern as _team/*.md + _data/team/*.yml → profile.html). YAML over CSV/JSON: editors already hand-edit it; native to Jekyll, no plugin; forgiving for web-UI edits; diffs line-by-line; expresses one-to-many cells (CSV can't — that's what killed faculty.tsv).

timezone: Africa/Johannesburg
display_timezones: [Africa/Johannesburg, America/New_York, ...]  # renderer loops → replaces DAIDD's 11 hand-built timezone files with 1 source
tracks: [main, "Section 1", "Section 2"]
faculty: [pulliam, dushoff, abbott]        # roster: keys into people data; each must resolve
days:
  - date: 2025-12-08
    collapsible: true                      # → <details> wrapper
    sessions:
      - {start: "16:00", end: "16:30", kind: session, track: "Section 1",
         title: "Welcome", shadow: false, instructors: [pulliam], links: [...], notes: [...]}

Every verified irregularity maps: parallel tracks (track+tracks), multi-instructor (instructors[] keys), .shadow faculty-only rows (shadow:true → a separate gated build, stripped from public _site), <details> (collapsible), 11 timezone views (one source + display_timezones loop), no-time bullets (notes[]/start:null), non-contiguous cohorts (absent file = absent year), external links stored verbatim (links[].url).

Validator tiers (maps to "build vs wrong")

• Tier 0 — schema: required-fields-per-kind, enums, ISO date / HH:MM, declared tracks. Also kills today's silent people-join failures (orphans, corrupt files, typo'd type).
• Tier 1 — semantic/referential (hard-fail): every instructor/faculty key resolves; sessions monotonic & non-overlapping within a track; end ≥ start.
• Tier 2 — link-liveness (advisory, non-gating): weekly job files an issue on 4xx/5xx (Drive returns non-200 for valid private links — never block on it).

Preview path (the human-factors fix — not optional)

Add a per-PR render/preview URL so a non-developer sees the rendered schedule before it goes live. This is what the abandoned perl/Make toolchain lacked; running it in CI means nobody installs anything locally. Without it, the new model is a weaker safety net than what was abandoned.

First deliverable — the experiment

Extract the current + a couple of previous MMED schedules into the flat file, draft the schema + validator, then have a representative non-engineer faculty editor make a change and confirm validation + preview catch problems. Widen the corpus beyond recent MMED: test the in-repo DAIDD archives (daidd/schedule/2013–2017.md), a gapped cohort, and the timezone case. Add a raw-HTML passthrough escape hatch (explicitly out-of-guarantee) so a too-strict schema never pushes faculty back to inline HTML. Part of #58; sharing of the renderer handled in #56.

[WestonVoglesonger]

Part of #58 (epic). Related spikes: #53 #54 #55 #56 #57. The #TBD cross-refs in the body resolve to these — to be tidied during refinement.