Zettle

0015-resource-schema

2 min read

ADR-0015: Resource note schema

Status: Accepted Date: 2026-05-19

Context

CONTEXT.md defined schemas for atomic/thread/sermon/question/person/glossary but left resource files implicit. As we begin actual ingestion (Believers’ Responsibility), we need an explicit shape for what a resource file looks like — frontmatter, headings, anchor convention.

Decision

A resource file has YAML frontmatter + cleaned body text + AI-inserted ## section headings (per ADR-0003 and the per-class grammar in CONTEXT.md).

---
type: resource
class: BR                            # short code, matches CONTEXT.md citation grammar table
title: "Introduction"
book: "The Believer's Responsibility"   # full book/work title, for query
author: "Tyler Hendricks"
year: 2010
chapter: 0                            # chapter or section number; null for one-piece works
source-file: "resources-raw/Believers-Responsibility/BelieversResponsibility.pdf"
ingested: 2026-05-19
---
 
## Section heading
Body paragraphs — cleaned of OCR noise.
 
## Another section
More paragraphs.
 
---
 
## Footnotes
 
[^1]: footnote text
[^2]: footnote text

Rules:

  • ## headings are the citation anchor targets. Citations resolve as [[{folder}/{chapter-file}#section-heading|section-heading]].
  • Heading slug auto-derives from the heading text (Obsidian convention). Atomics cite headings by their visible text.
  • Page numbers, OCR noise, and mangled title lines are cleaned during ingestion.
  • Footnotes preserved under ## Footnotes at end of file.

Ingestion process

Per ADR-0009’s Ingestion Review Gate:

  1. AI inspects the raw source (PDF or rough markdown) and proposes: cleaned chapter file with frontmatter + AI-chosen ## section headings + footnotes
  2. AI shows user the result (one chapter at a time during pilot; could batch later)
  3. User reviews — confirms section breaks are sensible, OCR cleanup is correct
  4. On approval, AI proceeds to atomize from the chapter

Alternatives considered

  • No frontmatter on resources: rejected — frontmatter enables queries (every BR chapter, every work by Hendricks) and tracks provenance.
  • Single H1 per chapter, no inner sections: rejected — defeats anchor-based citations; readers can’t jump to specific passages.
  • Use OCR page numbers as anchors (#p7): rejected — page boundaries are mid-paragraph artifacts, semantically meaningless; AI-inserted topical sections are more useful for both citation and reading.

Consequences

  • (+) Every cited passage has a real anchor; readers can jump straight to it on the published site
  • (+) Frontmatter enables sweep queries (“all atomics citing Hendricks”, “all resources from 2010”)
  • (+) Cleaned text makes for higher-quality atomization (no OCR garbage propagating into atomics)
  • (−) Section-break decisions are interpretive — must pass through the ingestion review gate
  • (−) Per-chapter cleaning effort is real; for sources with consistent OCR quality, this can be partially scripted later

Graph View