title	GENEALOGIX Specification
description	Modern, evidence-first, Git-native genealogy data standard
layout	doc

GENEALOGIX Specification

The official specification for GENEALOGIX (GLX) - a portable, extensible archive format for genealogical research and beyond. Built on Git, designed for collaboration, and customizable through archive-owned vocabularies. Your data, your way, forever.

Quick Links

• 📖 Read the Specification
• 📋 JSON Schemas
• 💡 Examples
• 🧪 Test Suite
• 🛠 CLI
• 🧱 Dev Container

Why GENEALOGIX?

Traditional genealogy formats like GEDCOM have served researchers well, but they have limitations in the modern collaborative research environment. GENEALOGIX addresses these challenges with a fresh approach.

The Problem with Traditional Formats

Challenge	GEDCOM	GENEALOGIX
Collaboration	File sharing only	Git-native workflows
Evidence Tracking	Basic source records	Complete evidence chains
Version Control	Manual or difficult	Built-in Git integration
Human Readability	Don't even try	Clear YAML structure
Validation	Syntax only	Schema-based validation
Extensibility	Limited	JSON Schema based
Data Portability	Vendor lock-in	Open format you own
Interoperability	GEDCOM export only	Import/export + Git workflows
Custom Types	Fixed schema	Archive-defined vocabularies

Visual Comparison

GEDCOM Format:

0 @I1@ INDI
1 NAME John /Smith/
1 BIRT
2 DATE 15 JAN 1850
2 PLAC Leeds, Yorkshire, England
2 SOUR @S1@
3 QUAY 2

GENEALOGIX Format:

persons:
  person-john-smith:
    properties:
      name:
        value: "John Smith"
        fields:
          given: "John"
          surname: "Smith"
      gender: "male"

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

assertions:
  assertion-john-birth:
    subject:
      event: event-birth-john
    property: date
    value: "1850-01-15"
    citations: [citation-birth-cert]
    confidence: high

Learn More: See Core Concepts for the complete assertion model and evidence chain explanation.

Beyond Exchange: A True Research Foundation

GENEALOGIX is more than an import/export format. It's a permanent foundation for your research:

Data You Own and Control

• Human-readable YAML - Edit in any text editor, no special software required
• Open format - No proprietary database, no vendor lock-in
• Portable forever - Your data outlasts any software application
• Git-native - Industry-standard version control built in

Flexible to Your Research Domain

• Custom vocabularies - Define your own event types, relationship types, properties
• Beyond genealogy - Biography projects, local history, prosopography, and more
• Extensible schema - Add custom fields without breaking compatibility
• No central registry - Each archive is autonomous and self-contained

Built for Collaboration

• Git workflows - Branch, merge, and collaborate like software developers
• Evidence-first - Every claim backed by documented sources
• Conflict resolution - Handle competing evidence systematically
• Pull request reviews - Quality assurance through peer review

What is GENEALOGIX?

GENEALOGIX is an open standard for version-controlled family archives that provides:

• 📚 Evidence-First Model: Every claim backed by documented sources
• 🔍 Quality Assessment: Structured evaluation of evidence reliability (0-3 scale)
• 🌳 Git-Native Architecture: Full version control and collaboration support
• 📋 Human-Readable Format: Clear YAML files instead of binary formats
• ✅ Schema Validation: JSON Schema-based validation and error checking
• 🔗 Complete Provenance: Audit trail from repository to conclusion
• 🎯 Repository-Owned Vocabularies: Define custom types within each archive

Installation

The recommended way to install the glx CLI is to download the latest pre-compiled binary for your operating system from the GitHub Releases page.

Alternatively, developers can install from source:

# Install the glx CLI tool
go install github.com/genealogix/glx/glx@latest

Quick Start

# Create a new genealogix repository in a new directory
glx init my-family-archive

# Or create a single-file archive
glx init my-family-archive --single-file

# Validate .glx files (checks cross-references and vocabularies)
cd my-family-archive
glx validate

File Format

All GENEALOGIX files use the same structure:

# Any .glx file
persons:
  person-a1b2c3d4:
    properties:
      name:
        value: "John Smith"
        fields:
          given: "John"
          surname: "Smith"
      gender: "male"

sources:
  source-12345678:
    title: "Birth Certificate"

Key Points:

• Entity IDs are map keys: person-john-smith or person-a1b2c3d4
• IDs can be descriptive or random (1-64 alphanumeric/hyphens)
• Files can contain any combination of entity types
• Parser collates all entities across all .glx files in repository
• Controlled vocabularies define valid types in vocabularies/ directory

Specification Status

This specification follows Semantic Versioning.

• Draft: Under active development, may change significantly
• Release Candidate: Stable, final review before release
• Released: Production-ready, changes discussed via GitHub issues and discussions

Community & Support

GENEALOGIX is an open-source project that thrives on community participation:

🐛 Issues & Bug Reports

• GitHub Issues - Report bugs and request features

💬 Discussion & Q&A

• GitHub Discussions - Community conversations
• Discord Community - Real-time chat and support
• Mailing List - Email discussions

📚 Documentation & Learning

• Quickstart Guide - 5-minute getting started
• Best Practices - Recommended workflows
• Migration Guide - Manual conversion guidance from GEDCOM
• Glossary - Key terms and concepts

🤝 Contributing

• Contributing Guide - How to contribute to the project
• Code of Conduct - Community standards

🎯 Getting Help

For Users:

1. Start with the Quickstart Guide
2. Explore Complete Examples
3. Ask questions in GitHub Discussions

For Developers:

1. Read CLAUDE.md for project context
2. Review the Contributing Guide
3. Check GitHub Issues and Discussions
4. Follow Best Practices

📊 Project Status

Current Release: v0.0.0-beta.9 (Beta)

• ✅ 9 core entity types defined
• ✅ JSON Schema validation
• ✅ CLI tool with vocabulary-based validation
• ✅ Repository-owned controlled vocabularies
• ✅ Complete test suite
• ✅ Comprehensive examples
• 🔄 Community building and feedback
• 📋 GitHub issues and discussions for major changes

🙏 Acknowledgments

GENEALOGIX builds on decades of genealogy research and the contributions of:

• The genealogy community for identifying core requirements
• Open-source projects like GEDCOM, Gramps, and FamilySearch
• Contributors who help improve the specification
• Researchers who provide real-world use cases

---

Made with ❤️ for genealogists, by genealogists

⭐ Star us on GitHub • 🐛 Report Issues • 💬 Join Discussions

License

Copyright 2025 Oracynth, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.