GENEALOGIX Specification

Version 0.0.0-beta.6

Table of Contents

1. Introduction

   • Purpose and Scope
   • Design Principles
   • Terminology

2. Core Concepts

   • Archive-Owned Vocabularies
   • Entity Relationships
   • Data Types (Primitive, Temporal, Reference)
   • Properties and Assertions
   • Evidence Chain
   • Collaboration with Git

3. Archive Organization

   • Repository Layout
   • Naming Conventions
   • File Organization Patterns

4. Entity Types

   • Person - Individual records
   • Relationship - Connections between people
   • Event - 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 (not an entity type)

5. Standard Vocabularies

   • Standard vocabulary templates for archive initialization

6. Glossary

   • Key terms and definitions

Specification Status

This specification is under active development.

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

Key Features

• Assertion-Based Model: Every genealogical fact can be supported by explicitly tracked evidence
• Git-Native: Built from the ground up for version control
• Hierarchical Places: Supports complex place hierarchies with historical variations
• Extensible: Custom entity types and properties supported via archive-owned vocabularies

Quick Example

# persons/person-john-smith.glx
persons:
  person-john-smith-1850:
    properties:
      name:
        value: "John Smith"
        fields:
          given: "John"
          surname: "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
    participants:
      - person: person-john-smith-1850
        role: spouse
      - person: person-mary-brown-1852
        role: spouse

Getting Started

1. Read Introduction for overview
2. Review Glossary for key terms and definitions
3. Read Core Concepts to understand the architecture
4. Review Entity Types to understand data structure
5. Check Archive Organization for organization patterns
6. Review Standard Vocabularies for controlled type definitions
7. See examples/ for working examples
8. 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