GENEALOGIX Specification

Version 0.0.0-beta.1 (Beta)

Table of Contents

1. Introduction

   • Purpose and Scope
   • Design Principles
   • Terminology

2. Core Concepts

   • Assertion-Aware Data Model
   • Evidence Hierarchy
   • Provenance Tracking
   • Version Control Integration

3. Archive Organization

   • Repository Layout
   • Naming Conventions
   • File Organization Patterns

4. Entity Types

   • Person - Individual records
   • Relationship - Connections between people
   • Event/Fact - Occurrences in time and place
   • Place - Geographic locations with hierarchy
   • Assertion - Evidence-based conclusions
   • Source - Bibliographic resources
   • Citation - References to specific evidence
   • Repository - Institutions holding sources
   • Media - Photographs, documents, etc.
   • Vocabularies - Controlled type definitions

5. Standard Vocabularies

   • Standard vocabulary templates for archive initialization

6. Data Types

   • Primitive Types (string, date, integer, boolean)
   • Temporal Values
   • Reference Types

Normative References

This specification uses RFC 2119 keywords (MUST, SHOULD, MAY) for requirement levels.

Reading Guide

• Implementers: Start with Core Concepts and Entity Types
• Users: Start with Introduction and File Structure
• Contributors: Read the entire spec plus CONTRIBUTING.md

Specification Status

This specification is under active development.

• Version: 0.0.0-beta.1
• Status: Beta
• Stability: Unstable API (breaking changes possible)

Key Features

• Assertion-Based Model: Every genealogical fact is supported by explicitly tracked evidence
• Multi-Tenant: Supports family-level isolation within organizations
• Git-Native: Built from the ground up for version control
• Hierarchical Places: Supports complex place hierarchies with historical variations
• Evidence Quality: Supports GEDCOM QUAY standard (0-3 scale) for source reliability assessment; however, assertion confidence levels are the preferred GENEALOGIX approach and quality scales are customizable per archive
• Extensible: Custom entity types and properties supported via repository-owned vocabularies

Quick Example

# persons/person-john-smith.glx
persons:
  person-john-smith-1850:
    properties:
      given_name: "John"
      family_name: "Smith"
      gender: "male"
      born_on: "1850-01-15"
    notes: "Blacksmith in Leeds, Yorkshire"

# events/event-birth.glx
events:
  event-birth-john:
    type: birth
    date: "1850-01-15"
    place: place-leeds
    participants:
      - person: person-john-smith-1850
        role: subject

# relationships/rel-marriage.glx
relationships:
  rel-marriage-john-mary:
    type: marriage
    persons:
      - person-john-smith-1850
      - person-mary-brown-1852

Documentation Conventions

Internal Links

Internal links omit the .md file extension for VitePress compatibility:

• ✓ Good: Person Entity
• ✗ Bad: Person Entity

This works correctly in both VitePress-generated site and raw markdown viewers.

File Organization

Examples may show entities in single files or multiple files. Both are valid:

• Single file: Simpler for small examples and personal archives
• Multiple files: Better for collaboration (cleaner git diffs)

See Archive Organization for details.

Getting Started

1. Read Introduction for overview
2. Review Entity Types to understand data structure
3. Check Archive Organization for organization patterns
4. Review Standard Vocabularies for controlled type definitions
5. See examples/ for working examples
6. Use glx CLI for validation

Contributing

Major changes are discussed via GitHub issues and discussions. See CONTRIBUTING.md

License

This specification is licensed under the Apache License 2.0