GEDCOM File Parsing
Relevant source files
The following files were used as context for generating this wiki page:
The GEDCOM File Parsing system is a core module within the Vata application designed to handle the ingestion, validation, and structural decomposition of GEDCOM 5.5.1 files. Its primary purpose is to convert raw genealogy data into a structured internal representation (GedcomDocument) that can be subsequently imported into the application's SQLite-based tree databases.
Sources: src/gedcom-parser/types.ts:1-10, README.md:10-15
Architectural Overview
The parsing logic is organized into a multi-stage pipeline that ensures data integrity through early validation and specialized lexing. The system moves from raw string input to tokenized lines, and finally to a nested document object.
Data Flow Pipeline
The following diagram illustrates the transformation process from a raw .ged file to an imported family tree database:
The process begins with the GedcomManager orchestration layer, which triggers a scan for the UI preview before executing the full import.
Sources: src/managers/GedcomManager.ts:182-205, src/lib/gedcom/importer.ts:45-60
Core Components
1. Lexer and Tokenization
The lexer is responsible for decomposing the flat file into GedcomLine objects. It uses a regular expression ^(\d{1,2})\s+(?:@([^@]+)@\s+)?(\S+)(?:\s+(.*))?$ to capture the hierarchy level, optional XREF identifiers, tags (e.g., INDI, FAM), and values.
A critical role of the lexer is handling multi-line data through processContinuations. It merges CONC (concatenation) and CONT (continuation with newline) tags back into their parent records.
Sources: src/gedcom-parser/lexer.ts:15-25, src/gedcom-parser/lexer.ts:81-100
2. Validation System
Before full parsing, the validate function checks for structural requirements:
- Presence of
HEADandTRLR(trailer) records. - Verification of unique XREF identifiers for Individuals (
INDI) and Families (FAM). - Detection of invalid "level jumps" (e.g., skipping from level 0 to level 2).
- Identification of broken references (links to undefined XREFs).
Sources: src/gedcom-parser/validate.ts:19-50, src/gedcom-parser/validate.ts:100-115
3. Document Parser
The parser iterates through level-0 records to build a GedcomDocument. It handles specialized parsing logic for various genealogy structures:
| Entity | Description | Key Sub-tags Handled |
|---|---|---|
| Header | Metadata about the source app and version. | SOUR, VERS, GEDC, CHAR |
| Individual | Detailed person records. | NAME, SEX, BIRT, DEAT, FAMC, FAMS |
| Family | Relationship links between individuals. | HUSB, WIFE, CHIL, MARR, DIV |
| Event | Dated occurrences. | DATE, PLAC, TYPE, NOTE |
Sources: src/gedcom-parser/parse.ts:38-65, src/gedcom-parser/types.ts:40-100
GEDCOM Data Structures
The internal representation uses TypeScript interfaces to ensure type safety during the import process.
Importer Integration
The GedcomManager coordinates the interaction between the parser and the SQLite database. It performs a two-phase import to maintain relational integrity:
- Phase 1: Imports Individuals and creates their records in the
individualsandnamestables. - Phase 2: Imports Families and creates the links in the
family_memberstable using a mapping of GEDCOM XREFs to internal database IDs.
Sources: src/lib/gedcom/importer.ts:45-80, src/managers/GedcomManager.ts:60-90
Error Handling
During import, the system tracks statistics and errors. The ValidationResult provides the UI with counts of individuals, families, and any fatal errors or warnings found during the scan.
Sources: src/gedcom-parser/types.ts:182-200, src/managers/GedcomManager.ts:35-45
Conclusion
The GEDCOM parsing module provides a robust foundation for interoperability within Vata. By separating lexing, validation, and parsing into distinct stages, the system can gracefully handle the varied formatting found in genealogy files while ensuring that only structurally sound data reaches the internal SQLite storage.