GEN-JSON: A Modern Genealogy Data Format

GEN-JSON (Genealogy JSON) is an open, structured, and human-readable format for storing and sharing genealogical data. It serves as a modern replacement for the GEDCOM format, providing better flexibility, extensibility, and ease of use for genealogy applications, researchers, and AI/LLM systems.

Current Version: 3.0 - Optimized for AI/LLM access with denormalized shortcuts, natural language summaries, privacy controls, and typed event details.

• Human-Readable & Machine-Friendly - Clear JSON structures for better data handling
• AI/LLM Optimized - Natural language summary fields let LLMs answer 90% of queries from a single field
• Denormalized Shortcuts - born, born_place, died, died_place on individuals eliminate pointer-chasing
• Data Quality Tracking - Confidence levels and source quality indicators for research accuracy
• Comprehensive Event Support - Track all life events: birth, death, marriage, immigration, occupation, and more
• Typed Event Details - Standard detail schemas per event type (immigration, occupation, census, military, etc.)
• Privacy Controls - living and privacy fields for handling sensitive data about living persons
• Consistent Field Naming - source_ids, note_ids, media_ids for ID references; comments for inline text
• Hierarchical Places - Structured location data with coordinates for geocoding
• Rich Source Citations - Detailed metadata for historical records and research materials
• Internationalization Support - Uses UTF-8 for seamless global character encoding
• Works with Modern Web & Desktop Apps - Easily integrates with genealogy applications, APIs, and databases

{
  "version": "3.0",
  "schema_url": "https://gen-json.org/schemas/v3.0/gen-json-schema.json",
  "summary": "Doe family tree. 5 individuals across 3 generations.",
  "metadata": {},
  "individuals": {},
  "families": {},
  "events": {},
  "sources": {},
  "repositories": {},
  "media": {},
  "places": {},
  "notes": {}
}

• summary - Natural language overview of the entire tree for LLM consumption
• schema_url - Link to the JSON Schema this file conforms to
• metadata - File-level information (creator, timestamps, change log)
• individuals - People with structured names, summaries, denormalized shortcuts, and relationships
• families - Lightweight family groupings with partner_ids, child_ids, event_ids
• events - All life events (birth, death, marriage, immigration, occupation, etc.)
• sources - Detailed citations with quality ratings
• repositories - Archives and institutions holding source materials
• media - Images, documents, audio, video with metadata
• places - Hierarchical location data with coordinates
• notes - Research notes with attribution and conflict tracking

{
  "version": "3.0",
  "summary": "Doe family tree. 5 individuals across 3 generations. German immigrant family in New York.",
  "individuals": {
    "I1": {
      "summary": "John Doe Jr. (1900-1985). Born Jan 1, 1900 in New York, NY. Died Mar 15, 1985 in Los Angeles, CA. Son of William Doe and Mary Johnson. Married Jane Smith. Immigrated from Germany c. 1920. Carpenter 1925-1960.",
      "name": {
        "given_name": "John",
        "surname": "Doe",
        "suffix": "Jr.",
        "full_name": "John Doe Jr."
      },
      "sex": "M",
      "born": "1900-01-01",
      "born_place": "New York, New York, USA",
      "died": "1985-03-15",
      "died_place": "Los Angeles, California, USA",
      "living": false,
      "privacy": "public",
      "events": ["E1", "E2", "E3"],
      "parents": [
        { "individual_id": "I3", "relationship_type": "biological", "parent_type": "father" }
      ],
      "source_ids": ["S1", "S2"],
      "confidence_level": "high"
    }
  },
  "events": {
    "E1": {
      "type": "birth",
      "individual_id": "I1",
      "date": { "value": "1900-01-01", "date_type": "exact" },
      "place_id": "P1",
      "source_ids": ["S1"]
    },
    "E2": {
      "type": "immigration",
      "individual_id": "I1",
      "date": { "value": "1920", "date_type": "approximate" },
      "details": {
        "vessel_name": "SS Bremen",
        "from_country": "Germany",
        "arrival_port": "New York Harbor"
      }
    }
  },
  "places": {
    "P1": {
      "name": "New York, New York, USA",
      "components": {
        "locality": "New York",
        "state": "New York",
        "country": "United States"
      },
      "coordinates": { "latitude": 40.7128, "longitude": -74.0060 }
    }
  }
}

See examples/example-v3-comprehensive.json for a complete example with all v3.0 features.

Load a GEN-JSON file into any JSON-compatible system. Use JavaScript (Node.js, Deno), Python (json module), or any other language that supports JSON.

Using the included Node.js validator:

node tools/gen-json-validator.js examples/example-v3-comprehensive.json

Using ajv-cli (if installed globally):

ajv validate -s schemas/gen-json-schema.json -d my-family-tree.json

A Python script converts GEDCOM files to GEN-JSON v3.0:

python tools/gedcom-to-genjson.py input.ged output.json

Options:

• --verbose - Enable detailed logging
• --compact - Output minified JSON
• --skip-empty - Omit empty fields

The converter automatically generates summaries, denormalized shortcuts, structured events, and places from GEDCOM data.

GEN-JSON v3.0 is designed around how LLMs actually process data:

• Summary Fields - Natural language biographies let LLMs answer most queries from a single field
• Denormalized Shortcuts - born, died, born_place, died_place eliminate pointer-chasing across sections
• Structured Data - Names, places, and dates are pre-parsed for direct field access
• Explicit Uncertainty - Date types and confidence levels enable probabilistic reasoning
• Typed Event Details - Standard schemas per event type (immigration, occupation, census, etc.)
• Privacy Controls - living and privacy fields help LLMs respect sensitive data
• Graph-Ready - Clean ID references for knowledge graphs and relationship analysis

Example AI queries:

// "Tell me about John Doe" -> read one field
const person = genJson.individuals['I1'];
console.log(person.summary);
// "John Doe Jr. (1900-1985). Born Jan 1, 1900 in New York, NY..."

// "When was John born?" -> direct field access, no pointer-chasing
console.log(person.born);       // "1900-01-01"
console.log(person.born_place); // "New York, New York, USA"

// "What were John's occupations?" -> filter events by type
const occupations = person.events
  .map(eid => genJson.events[eid])
  .filter(e => e.type === 'occupation');

• Summary Fields - Natural language biographies on individuals and the root level
• Denormalized Shortcuts - born, born_place, died, died_place on individuals
• Privacy Controls - living boolean and privacy enum (public/restricted/private)
• Typed Event Details - Standard detail schemas for immigration, occupation, census, military, education, residence, naturalization
• Consistent Field Naming - source_ids, note_ids, media_ids for ID references; comments for inline text
• Simplified Place References - Events use place_id (string) or place_text (fallback) instead of nested objects
• Simplified Families - partner_ids, child_ids, event_ids as lightweight grouping
• Removed circa - Redundant with date_type: "approximate"
• Removed gender object - sex field is sufficient for genealogical data
• Source of Truth Doctrine - Explicit documentation of authoritative data locations

• Specification (v3.0) - Complete format specification
• Examples - Sample files
  • example-v3-comprehensive.json - Full v3.0 demonstration
• Integration Guide - How to use GEN-JSON with genealogy software

GEN-JSON is released under the MIT License. See LICENSE for details.

Discussions: GitHub Issues Wiki: GEN-JSON Wiki

Start using GEN-JSON today to preserve and share your family history!