GEDCOM 5.5.1 Import & Export Workflow

Relevant source files

The following files were used as context for generating this wiki page:

• src/managers/GedcomManager.ts
• src/lib/gedcom/importer.ts
• src/lib/gedcom/exporter.ts
• src/gedcom-parser/parse.ts
• src/gedcom-parser/types.ts
• src/gedcom-parser/validate.ts
• src/components/trees/import-gedcom-modal.tsx
• src/gedcom-parser/lexer.ts

The GEDCOM 5.5.1 workflow in Vata provides the core mechanism for genealogy data interoperability. It enables users to import existing family tree data from standard .ged files into local SQLite databases and export their research back to the GEDCOM format. The system is designed with a "local-first" philosophy, ensuring that all parsing, validation, and serialization occur entirely on the user's machine without external dependencies.

Sources: README.md:14-15, src/managers/GedcomManager.ts:1-10

System Architecture

The workflow is orchestrated by the GedcomManager, which coordinates between the UI layer, the low-level GEDCOM parser, and the database-specific importer/exporter libraries.

Core Components

Component	Responsibility
GedcomManager	High-level orchestration, file system interactions (Tauri), and tree lifecycle management.
Gedcom Parser	Low-level tokenization (lexer.ts), structural validation (validate.ts), and semantic parsing (parse.ts).
GEDCOM Importer	Transforms parsed GedcomDocument objects into SQLite relational records using a two-phase strategy.
GEDCOM Exporter	Queries the SQLite tree database and serializes entities into the lineage-linked GEDCOM 5.5.1 format.

Sources: src/managers/GedcomManager.ts:13-25, src/lib/gedcom/importer.ts:1-12, src/lib/gedcom/exporter.ts:1-10

Import Workflow

The import process involves a multi-stage pipeline that ensures data integrity before modifying the local system database.

1. Pre-import Scan and Validation

Before a file is imported, it undergoes a "Scan" phase. The GedcomManager.scan function uses the validate utility to count top-level records (Individuals, Families, Sources, Repositories) and identify structural errors or warnings.

2. Two-Phase Database Import

The importGedcom function in src/lib/gedcom/importer.ts utilizes a transaction-wrapped, two-phase strategy to handle cross-references:

• Phase 1: Individuals: Creates individuals, names, and events (Birth, Death, etc.). It caches the mapping between original GEDCOM XREFs (e.g., @I1@) and new internal SQLite primary keys.
• Phase 2: Families: Creates families and family_members records. It uses the XREF cache from Phase 1 to link husband, wife, and children to their respective family units.

Export Workflow

The export workflow reverses the import process, extracting data from the relational SQLite schema and formatting it for standard GEDCOM serialization.

Export Pipeline

1. XREF Assignment: Since SQLite uses integer IDs and GEDCOM requires alphanumeric XREFs, the exporter first maps every ID to a standard string (e.g., I1, F1).
2. Data Extraction: Queries individuals, names, events, and family structures.
3. Serialization: The serialize utility converts the object model into a text-based format, handling line length constraints (255 characters) using CONC (concatenation) and CONT (continuation) tags.

Technical Implementation Details

Lexing and Continuation Processing

The GEDCOM format uses a strictly leveled structure. The lexer handles line normalization and merges CONC and CONT tags to reconstitute long text values.

// Example from src/gedcom-parser/lexer.ts
export function processContinuations(lines: GedcomLine[]): GedcomLine[] {
  const result: GedcomLine[] = [];
  for (const line of lines) {
    if (line.tag === 'CONC' && result.length > 0) {
      result[result.length - 1].value += (line.value || '');
    } else if (line.tag === 'CONT' && result.length > 0) {
      result[result.length - 1].value += '\n' + (line.value || '');
    } else {
      result.push({ ...line });
    }
  }
  return result;
}

Sources: src/gedcom-parser/lexer.ts:81-98

Privacy Filtering

During export, Vata implements a privacy filter. By default, the exportToFile function can exclude living individuals to protect sensitive data when sharing research.

• Living Check: In the exporter, individuals are filtered based on the is_living flag unless includePrivate is explicitly set to true.
• Reference Integrity: The exporter skips family links if one or more members are excluded due to privacy settings.

Sources: src/lib/gedcom/exporter.ts:101-115, src/lib/gedcom/exporter.ts:215-230

Conclusion

The GEDCOM 5.5.1 Import & Export Workflow is a robust system that bridges the gap between Vata's relational SQLite storage and the industry-standard interchange format. By implementing a detailed validation and a two-phase import strategy, the application ensures that complex family relationships and event participants are preserved accurately during data transitions. The modular design of the gedcom-parser allows for future expansion into additional records like Sources and Repositories, which are currently scoped as placeholders in the data types.

Sources: src/gedcom-parser/types.ts:10-30, src/lib/gedcom/importer.ts:315-325