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.

Installation

Download the latest pre-compiled binary for your operating system from the GitHub Releases page.

Developers can install from source:

# Pin the release tag for a reproducible install; bump it when a new release ships
go install github.com/genealogix/glx/[email protected]

# Or track main for changes not yet in a release. `glx --version` then
# reports the commit it was built from (a pseudo-version ending in its hash).
go install github.com/genealogix/glx/glx@main

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

Why GENEALOGIX?

Traditional formats like GEDCOM solve file exchange but stop short of modern collaborative research. GENEALOGIX is a Git-native, evidence-first archive format that aims to be a permanent foundation, not just an export target.

For a side-by-side look at the GEDCOM-vs-GLX wire formats and the assertion model that backs every claim with evidence, see Core Concepts.

Features

• 📚 Evidence-First Model — every claim backed by documented sources
• 🔍 Quality Assessment — structured confidence on every assertion, with the nature of the source and of the information recorded separately
• 🌳 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

CLI Commands

The glx CLI groups its commands into archive management, import/export, exploration, data entry, analysis, and shell completion. Run glx --help for the list your build has, glx <command> --help for a command's flags, or see the CLI reference for per-command pages with examples.

Archive Management

• glx init — initialize a new archive
• glx validate — validate files and cross-references
• glx split — convert a single-file archive to multi-file
• glx join — convert a multi-file archive to single-file
• glx merge — combine two archives with duplicate detection
• glx merge-persons — merge two person records into one
• glx migrate — migrate an archive to the current format
• glx rename — rename an entity by ID
• glx cache — build, inspect, or clear the binary archive cache

Import & Export

• glx import — import a GEDCOM file
• glx export — export to GEDCOM or Schema.org-aligned JSON-LD
• glx publish — generate a self-contained static HTML site from an archive

Exploration

• glx search — full-text search across entities
• glx query — filter and list entities
• glx vitals — show birth, death, burial for a person
• glx timeline — chronological events for a person
• glx summary — full person profile with narrative
• glx ancestors — ancestor tree
• glx descendants — descendant tree
• glx cite — formatted citation text
• glx path — shortest relationship path between two people
• glx serve — local browser-based read-only archive viewer

Data Entry

• glx census — census tooling (see subcommands)
• glx census add — generate entities from a census template
• glx add — create entities (person, place, event, source, citation, repository, relationship, assertion, and more) from flags; glx add --help lists every entity type
• glx link — create a FamilySearch citation (and source/repository scaffolding) from an ARK URL

Analysis

• glx stats — entity-count and confidence dashboard
• glx places — place data quality issues
• glx cluster — FAN-club analysis
• glx households — reconstruct census households for a person or a place
• glx analyze — gap, conflict, and suggestion analysis
• glx duplicates — detect duplicate entities
• glx coverage — research coverage report
• glx diff — diff two archives
• glx evidence — lay out every assertion for one subject+property side-by-side
• glx proof — compile a Genealogical Proof Standard summary for a research question
• glx migrations — trace a person's geographic movement over time

Shell completion

• glx completion — generate shell completion scripts (bash, zsh, fish, powershell)

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"
      sex: "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, except under dot-prefixed directories (.git, .glx, editor scratch dirs), which are not archive content
• Controlled vocabularies define valid types in vocabularies/ directory

Documentation

• 🚀 Quickstart — 5-minute getting started
• 💡 Examples — runnable sample archives
• 🛠 CLI Reference — every command and flag
• 📐 Best Practices — recommended workflows
• 🔁 Migration from GEDCOM — manual conversion guidance
• 🔀 GLX-aware Git merge driver — genealogy-aware conflict resolution for .glx files
• 📖 Specification — full spec
• 📋 JSON Schemas — machine-readable schemas
• 📚 Glossary — key terms and concepts
• 🧱 Dev Container — preconfigured dev environment

Specification Status

This specification follows Semantic Versioning. Current release: v0.0.0-beta.12 (Beta).

• 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

Topic	Where
Issues & bug reports	github.com/genealogix/glx/issues
Discussions & Q&A	github.com/genealogix/glx/discussions
Chat	Discord
Mailing list	groups.google.com/g/genealogix
Contributing	CONTRIBUTING.md
Code of Conduct	CODE_OF_CONDUCT.md
Security	SECURITY.md · SECURITY-POSTURE.md (OSPS Baseline, EU CRA readiness)
Releases	GitHub Releases

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.

Attribution for the third-party components bundled in GLX is listed in the NOTICE file.