11 RELAX NG Layer

pdai-structure.rnc governs structure.xml — orthogonal to page DTDs

11.1 What RELAX NG governs

The RELAX NG schema pdai-structure.rnc governs structure.xml, not page XML. It is orthogonal to the DTD system: page DTDs govern single OCR’d pages; RELAX NG governs the assembled document-level argumentative structure.

The two systems operate at different granularities:

Scope	Grammar	File
One OCR’d page	DTD	`config/page.dtd`
Assembled record (letter, catalogue entry)	DTD	`config/<record>.dtd`
Document-level argument structure	RELAX NG	`pdai-structure.rnc`

11.2 Structure.xml

structure.xml is the PDAI document-level source of truth for running text organised by argumentative hierarchy. It is produced by the ai-scholar structure sub-app:

ai-scholar structure extract --doc-id E57
ai-scholar structure validate --doc-id E57
ai-scholar structure ingest --doc-id E57

The RELAX NG schema lives at format/lettre-pdai/src/lettre_pdai/schemas/pdai-structure.rnc.

11.3 Structure element inventory

<structure doc_id="E57" collection="enestroem" lang="la">
  <section type="chapter" n="1">
    <heading>De viribus electricis</heading>
    <argument>
      <claim>...</claim>
      <evidence ref="page_057_3"/>
      <reasoning>...</reasoning>
    </argument>
    <section type="subsection" n="1.1">
      ...
    </section>
  </section>
</structure>

Key element types:

Element	Role
`<structure>`	Root; carries `doc_id`, `collection`, `lang`
`<section>`	Hierarchical division; `type` ∈ `chapter`, `section`, `subsection`
`<heading>`	Section title text
`<argument>`	One argumentative unit
`<claim>`	The stated proposition
`<evidence>`	Page-level source reference via `ref`
`<reasoning>`	Logical connection between evidence and claim

11.4 RELAX NG vs DTD tradeoffs

PDAI uses DTDs for page and record grammars because: - DTD validation is available in all standard XML parsers (lxml, Python xml.etree) without additional dependencies. - OCR runners write XML and validate in the same process; DTD validation adds negligible overhead.

RELAX NG is used for structure.xml because: - structure.xml has interleaved content models that are inexpressible in DTD. - The <argument> / <evidence> relationship is context-dependent in ways that require RELAX NG’s interleave and choice operators. - structure.xml is produced by an AI agent, not directly by the OCR runner, so the validation toolchain (Jing, lxml relaxng) is already available.

11.5 Connection to ai-query

The structure.xml layer feeds into the ai-query artifact engine (proof-structure from structure.xml, D3 force graph, timeline, KWIC). When ai-query resolves a query about argumentative structure in an edition, it reads structure.xml through the pdai_document_agent sub-system.

The RELAX NG contract file is documented in format/lettre-pdai/docs/structure-contract.md (previously an unlinked file; it is now referenced from the main Quarto book index).