gedcom-x 0.5.8

Python implimentation of gedcom-x standard

GEDCOM-X Python Toolkit (gedcom-x beta 0.5.5)

A lightweight, class-based Python implementation of the GEDCOM-X data model.

⚠️ Project Status

This project is currently in beta.
While the core GEDCOM-X classes and serialization are functional, some features may not be fully implemented or may not behave exactly as expected.

• Certain GEDCOM 7 tags are not yet mapped
• Some classes may be missing methods or fields
• Error handling and validation are still evolving
• Backward compatibility is not guaranteed until the first stable release

✅ What You Can Do

• Create and manipulate GEDCOM-X objects in Python
• Serialize and deserialize data to/from JSON
• Experimentally convert GEDCOM 5x & 7 files into GEDCOM-X JSON
• Extend the classes to handle new GEDCOM tags or custom attributes
• Use the library as a foundation for genealogy-related tooling or RAG pipelines

❌ What You Can’t Do (Yet)

• Rely on complete coverage of all GEDCOM 7 tags
• Expect perfect compliance with the GEDCOM-X specification
• Assume strong validation or error recovery on malformed input
• Use it as a drop-in replacement for production genealogy software
• Write GEDCOM-X to GEDCOM 5x / 7
• Create Graphs from Genealogies

Contributors and testers are welcome — feedback will help stabilize the library!

---

This library aims to provide:

• Python classes for every GEDCOM-X type (Person, Fact, Source, etc.)
• Extensibility, with current GEDCOM RS etc, extension built in
• Serialization and Deserialization to/from GEDCOM-X JSON
• Utilities to convert GEDCOM 5x & 7 GEDCOM Files into GEDCOM-X and back
• Type-safe field definitions and extensibility hooks for future tags

---

Features

• Complete GEDCOM-X Class Coverage
  Each GEDCOM-X type is represented as a Python class with fields and types.

• Serialization / Deserialization
  Every class can serialize to JSON and reconstruct from JSON via _as_dict_() and _from_json() methods.

• Type Checking & Enum Validation
  Uses Python type hints and enums to ensure correct values (e.g. FactType, EventType, ConfidenceLevel).

• Composable / Nestable Classes
  Nested objects (e.g. Person → Name → NameForm → TextValue) are constructed and validated recursively.

• GEDCOM 7 → GEDCOM-X Conversion
  Experimental parser to read GEDCOM 7 files and convert them into structured GEDCOM-X JSON.

---

Installation

Clone the repository and install dependencies:

git clone https://github.com/yourusername/gedcom-x.git
cd gedcom-x
pip install -r requirements.txt

or

pip install gedcom-x

---

Examples

Create a Person Gedcom-X Type

import json
from gedcomx import Person, Name, NameForm, TextValue

person = Person(
    id="P-123",
    names=[Name(
        nameForms=[NameForm(
            fullText=TextValue(value="John Doe")
        )]
    )]
)

print(json.dumps(person._as_dict_,indent=4))

result

{
    "id": "P-123",
    "lang": "en",
    "private": false,
    "living": false,
    "gender": {
        "lang": "en",
        "type": "http://gedcomx.org/Unknown"
    },
    "names": [
        {
            "lang": "en",
            "nameForms": [
                {
                    "lang": "en",
                    "fullText": {
                        "lang": "en",
                        "value": "John Doe"
                    }
                }
            ]
        }
    ]
}

</details>