ponomar-pwa/.ai-specs/DATA_MODEL_SPEC.md

Data Model Specification

CId (Canonical Identifier) System

Format Rules

CIds are identifiers for saints, feasts, and liturgical elements. They follow these routing rules:

CId Pattern	Target File	Examples	Notes
01XX-01ZZ	01.json	010101, 014567	January saints
02XX-02ZZ	02.json	023456, 027890	February saints
...	...	...	...
12XX-12ZZ	12.json	123456, 127890	December saints
Other CIds	misc/{first-digit}.json	772426→misc/7.json, 373→misc/3.json	Non-month-prefixed

Routing Logic

function bundleFileForCid(cid: string): string {
  return /^(0[1-9]|1[0-2])\d+/.test(cid) 
    ? `${cid.substring(0, 2)}.json` 
    : `misc/${cid.charAt(0)}.json`;
}

Menaion Bundle Structure

Format Definition

{
  "MM-DD": [
    { "id": "CId" },
    { "id": "CId" }
  ]
}

Key Points:

• Each date key: "MM-DD" format (Julian calendar)
• Array of objects with only "id" field
• CIds correspond to actual commemorations on that date
• One per language: menaion-bundle.json, {lang}-menaion-bundle.json

Example

{
  "01-01": [
    { "id": "010101" },
    { "id": "772426" },
    { "id": "010102" }
  ]
}

Life Entry Structure

Format Definition

{
  "CId": {
    "name": {
      "nominative": "Прп. Сильвестра Печерского (XII)",
      "short": "Прп. Сильвестра Печерского",
      "genitive": "Прп. Сильвестра Печерского"
    },
    "life": {
      "id": "minei-0101-772426",
      "copyright": "Четьи-Минеи свт. Димитрия Ростовского",
      "text": "<p>Complete life text in HTML...</p>"
    }
  }
}

Required Fields

• CId: String key (the canonical identifier)
• name.nominative: Required field (validated by validate-data.ts)

Optional Fields

• name.short: Short name variant
• life.text: HTML content (only written when empty)
• life.id: Source identifier (e.g., "minei-0101-772426" or "bulgakov-...")
• life.copyright: Copyright string

Service Template Structure

Hierarchical JSON Format

{
  "ROYALHOURS": {
    "0": {
      "text": "In the name of the Father...",
      "type": "0"
    }
  },
  "MATINS": {
    "kathisma": {
      "text": "Kathisma content..."
    }
  }
}

Conditional Logic Markers

• P-prefix nodes: Optional content that may be included
• Var/I-prefix nodes: Conditional selection logic
• Plain nodes: Required content always included

Chetyi-Minei Source Format

Format Definition

{
  "MM-DD": [
    {
      "title": "Память святого X",
      "html": "<p>Content paragraphs...</p>"
    }
  ]
}

Key Characteristics

• Generated by convert-minei.ts from EPUB source
• Stored in scripts/output/minei.json (gitignored, 33MB)
• Titles and HTML are carefully extracted and parsed
• Footnotes collected and appended as "Примечания:" blocks

Bulgakov Source Format

Format Definition

{
  "MM-DD": [
    {
      "title": "20-го июля — Св. пророк Илия",
      "html": "<p>Content paragraphs...</p>"
    }
  ]
}

Key Characteristics

• Generated by convert-bulgakov.ts from "Настольная книга для священно-церковнослужителей" EPUB
• Stored in scripts/output/bulgakov.json (gitignored)
• Menaion section only (306 days, 332 entries)
• Secondary source: fills gaps, never overrides existing Minei content

File Organization Rules

Lives Files

• Location: static/data/{lang}/lives/
• Files:
  • 01.json through 12.json (month-prefixed CIds)
  • misc/0.json through misc/9.json (non-month-prefixed CIds, split by first digit)
• Routing: Based on first two digits of CId (month) or first digit (misc)

Menaion Files

• Location: static/data/{lang}/menaion/
• Files: bundied into menaion-bundle.json per language
• Purpose: Daily liturgical readings by date

Service Templates

• Location: static/data/{lang}/services/
• Shared: static/data/shared/services/templates/

Calendar Data

• Location: static/data/shared/calendar/
• Purpose: Movable feast calculations and metadata

Scripture / Paremia Data

• Location: static/data/shared/parimii/
• Monthly files: jan/full.json through dec/full.json
• Common files: common-saints/full.json, cheese-week/full.json, etc.
• Purpose: Old Testament readings for Vespers

Data Invariants

CId Consistency Rules

• Same CId must have consistent name across all languages
• Bundle CIds must have corresponding lives entries
• CIds that exist in bundle must have lives entries
• CIds with lives entries must exist in bundle for their date

File Organization Invariants

• No month file contains CIds with different month prefix
• misc/{n}.json contains all CIds with matching first digit
• All data files are tracked in static/data/

Content Validation Invariants

• All lives entries must have name.nominative field
• HTML content in life.text must be properly escaped
• JSON files must be parseable (no syntax errors)
• File routing must match CId prefixes consistently

Common Data Mistakes to Avoid

CId Pattern Errors

• ⚠️ Don't create CIds with invalid prefixes
• ⚠️ Don't put CIds in wrong month files
• ⚠️ Don't create duplicate CIds with different meanings

JSON Structure Errors

• ⚠️ Don't omit required fields (name.nominative)
• ⚠️ Don't nest structures incorrectly (service templates)
• ⚠️ Don't mix CId numbers and strings inconsistently
• ⚠️ Don't leave trailing commas in JSON

File Organization Mistakes

• ⚠️ Don't place month-prefixed CIds in misc files
• ⚠️ Don't create inconsistent JSON indentation
• ⚠️ Don't mix languages in incorrect directories

Examples

Valid CId Examples

• 010101 → 01.json (January saint)
• 1253 → 12.json (December saint)
• 772426 → misc/7.json (non-prefixed saint)

Invalid CId Examples

• 00501 → Should not exist (prefix 00 → misc)
• 13xxx → Should not exist (prefix 13 → misc)

File Routing Examples

• CId 1253 routes to 12.json
• CId 772426 routes to misc/7.json
• CId 373 routes to misc/3.json

Bundle Entry Examples

{
  "01-15": [
    { "id": "010201" },
    { "id": "772455" }
  ]
}

Life Entry Examples

{
  "772426": {
    "name": {
      "nominative": "Прп. Сильвестра Печерского (XII)",
      "short": "Прп. Сильвестра Печерского"
    },
    "life": {
      "id": "minei-0101-772426",
      "copyright": "Четьи-Минеи свт. Димитрия Ростовского",
      "text": "<p>Complete life content...</p>"
    }
  }
}

Current Project State

Coverage Statistics

• Total CIds: 3046
• Lives with text: 1203 (39% coverage)
• Sources: Chetyi-Minei (1190) + Bulgakov (13)
• Empty lives: 1843 (61% remain)

Data Files

• Lives bundle files: 12 month files (01-12) + 10 misc split files (0-9)
• Service template files: Multiple per language
• Parimii files: 12 monthly + common saints + triodion periods

Recent Changes

• Bundle fix: 868 Иаков Боровицкий moved from 05-22 to 10-23
• Minei enrichment: 64 manual fixes added
• Bulgakov enrichment: 9 manual fixes added, 13 new lives
• Coverage increase: 1009→1190→1203 lives with text