Relationship Entity

← Back to Entity Types

Overview

A Relationship entity defines a connection between two or more persons. Relationships can be biological (parent-child), legal (marriage, adoption), social (godparent), or custom types defined by the archive.

File Format

All GENEALOGIX files use entity type keys at the top level:

# Any .glx file (commonly in relationships/ directory)
relationships:
  rel-marriage-john-mary:
    type: marriage
    participants:
      - person: person-john-smith
      - person: person-mary-jones
    start_event: event-marriage-1875

Key Points:

• Entity ID is the map key (rel-marriage-john-mary)
• IDs can be descriptive or random, 1-64 alphanumeric/hyphens

Fields

Required Fields

Field	Type	Description
Entity ID (map key)	string	Unique identifier (alphanumeric/hyphens, 1-64 chars)
type	string	Relationship type from vocabularies/relationship-types.glx
participants	array	Array of participant objects defining who is in the relationship (at least 2 required)

Optional Fields

Field	Type	Description
properties	object	Vocabulary-defined properties for the relationship
start_event	string	Event that started this relationship
end_event	string	Event that ended this relationship
notes	string | string[]	Research notes

Properties

Relationship properties capture additional details that don't fit into the standard structural fields. The following are standard properties from the default vocabulary; archives can define additional properties by extending the vocabulary.

Property	Type	Description
started_on	date	When the relationship began
ended_on	date	When the relationship ended
location	reference	Location where the relationship occurred (reference to Place)
description	string	Detailed description of the relationship

Example:

relationships:
  rel-business-partnership:
    type: business-partner  # Custom type — define in your archive's vocabulary
    participants:
      - person: person-john-smith
      - person: person-james-brown
    properties:
      started_on: "1875-03-15"
      ended_on: "1890-06-01"
      location: place-leeds
      description: "Co-owners of Smith & Brown Ironworks"

See Vocabularies - Relationship Properties for the full vocabulary definition.

Relationship Types

Relationship types are defined in the archive's vocabularies/relationship-types.glx file. Each archive includes standard types and can define custom types as needed.

See Vocabularies - Relationship Types for:

• Complete list of standard relationship types
• How to add custom relationship types
• Vocabulary file structure and examples
• Validation requirements

Usage Patterns

Marriage Relationship

relationships:
  rel-marriage-john-mary:
    type: marriage
    participants:
      - person: person-john-smith
        role: spouse
      - person: person-mary-jones
        role: spouse
    start_event: event-marriage-1875
    properties:
      description: "Marriage at St Paul's Cathedral"

Note: Marriage Event vs Marriage Relationship

Marriage appears in both event types and relationship types by design:

• Event type marriage (Event Entity): The wedding ceremony - records the date, place, officiant, witnesses, and other ceremony details
• Relationship type marriage (this entity): The ongoing marital state - connects two spouses, tracks duration, and can reference when/how it ended

Link them using start_event to reference the ceremony. Use both when you have ceremony details; use just the relationship if you only know they were married without specifics about the wedding.

Parent-Child Relationship

relationships:
  rel-parents-alice:
    type: parent_child
    participants:
      - person: person-john-smith
        role: parent
      - person: person-mary-smith
        role: parent
      - person: person-alice-smith
        role: child

Adoptive Parent-Child Relationship

# The adoption event records the legal proceeding
events:
  event-adoption-1890:
    type: adoption
    date: "1890-03-15"
    place: place-county-court
    participants:
      - person: person-sarah-jones
        role: subject
    notes: "Legal adoption finalized"

# The relationship connects parent(s) and child
relationships:
  rel-adoptive-family-sarah:
    type: adoptive_parent_child
    participants:
      - person: person-james-smith
        role: adoptive_parent
      - person: person-elizabeth-smith
        role: adoptive_parent
      - person: person-sarah-jones
        role: adopted_child
    start_event: event-adoption-1890
    properties:
      description: "Sarah legally adopted by James and Elizabeth Smith"

Note: Adoption Event vs Adoptive Parent-Child Relationship

Similar to how marriage works in GLX:

• Event type adoption (Event Entity): The legal adoption proceeding - records the date, place, court, and other details of when the adoption was finalized
• Relationship type adoptive_parent_child (this entity): The ongoing parent-child relationship - connects adoptive parent(s) to the adopted child

Link them using start_event to reference the adoption event. Use both when you have details about when the adoption occurred; use just the relationship if you only know the relationship exists without specifics.

Godparent Relationship

# The baptism event records the ceremony where godparents were named
events:
  event-baptism-1885:
    type: baptism
    date: "1885-06-12"
    place: place-st-marys-church
    participants:
      - person: person-baby-william
        role: subject
      - person: person-uncle-james
        role: godparent
      - person: person-aunt-sarah
        role: godparent
    notes: "Baptism at St Mary's Church"

# The relationship represents the ongoing godparent-godchild bond
relationships:
  rel-godparent-james-william:
    type: godparent
    participants:
      - person: person-uncle-james
        role: godparent
      - person: person-baby-william
        role: godchild
    start_event: event-baptism-1885

Note: Godparent Event Role vs Godparent Relationship

Godparent appears in both participant roles and relationship types by design:

• Participant role godparent (Event Entity): A person's role at a baptism or christening ceremony - records who served as spiritual sponsor
• Relationship type godparent (this entity): The ongoing godparent-godchild bond that may continue throughout their lives

Use the participant role when recording event details; use the relationship type to model the ongoing connection. Link them with start_event when you have both.

Custom Relationship

relationships:
  rel-john-james-blood:
    type: blood_brother  # Custom type from vocabulary
    participants:
      - person: person-john-smith
      - person: person-james-brown
    start_event: event-ceremony-1845
    properties:
      description: "Blood brother ceremony witnessed by tribal elders"

Enslavement Relationship

Enslavement is modeled as a relationship with enslaver and enslaved_person roles, bounded by start_event and end_event so that successive enslavers — through sale, inheritance, or manumission — appear as distinct relationships with shared boundary events. Use the legal_status property to distinguish chattel slavery from indentured servitude, debt bondage, and apprenticeship-as-enslavement.

Single enslaver

relationships:
  rel-enslavement-jenny-by-thomas-1820-1834:
    type: enslavement
    participants:
      - person: person-thomas-pettus
        role: enslaver
      - person: person-jenny
        role: enslaved_person
    start_event: event-jenny-purchased-1820
    end_event: event-jenny-sold-1834
    properties:
      legal_status: chattel
      description: "Jenny appears in Thomas Pettus's 1820 bill of sale and 1834 estate division."

Multiple enslavers across a lifetime

When an enslaved person was sold or inherited, model each enslaver as a separate relationship. The same transfer event closes one relationship and opens the next, preserving the audit trail through the shared event:

events:
  event-jenny-sold-1834:
    type: sale
    date: "1834-04-12"
    place: place-campbell-co-va
    participants:
      - person: person-jenny
        role: subject

relationships:
  rel-enslavement-jenny-by-thomas-1820-1834:
    type: enslavement
    participants:
      - person: person-thomas-pettus
        role: enslaver
      - person: person-jenny
        role: enslaved_person
    start_event: event-jenny-purchased-1820
    end_event: event-jenny-sold-1834
    properties:
      legal_status: chattel

  rel-enslavement-jenny-by-william-1834-1851:
    type: enslavement
    participants:
      - person: person-william-cabell
        role: enslaver
      - person: person-jenny
        role: enslaved_person
    start_event: event-jenny-sold-1834
    end_event: event-jenny-manumitted-1851
    properties:
      legal_status: chattel

Inherited enslavement (partus sequitur ventrem)

Children born to enslaved mothers were legally enslaved at birth in most U.S. slaveholding jurisdictions before emancipation. Model this as two relationships citing the same source — a parent_child link to the mother and an enslavement link to the mother's enslaver at the time of birth:

relationships:
  rel-parent-jenny-sarah:
    type: parent_child
    participants:
      - person: person-jenny
        role: parent
      - person: person-sarah
        role: child
    start_event: event-sarah-born-1828

  rel-enslavement-sarah-by-thomas-1828:
    type: enslavement
    participants:
      - person: person-thomas-pettus
        role: enslaver
      - person: person-sarah
        role: enslaved_person
    start_event: event-sarah-born-1828
    properties:
      legal_status: chattel
      description: "Sarah enslaved at birth by Pettus per partus sequitur ventrem; both relationships attested by the 1830 plantation inventory."

Apprenticeship as continued enslavement

Between 1865 and 1867 in several former slaveholding states, "apprenticeship" became the legal mechanism by which freed children of color were bound back to their former enslavers under Black Code statutes — arrangements structurally indistinguishable from chattel slavery but classified differently in court records. Model these with the same enslavement relationship type, distinguished by legal_status: apprenticeship:

relationships:
  rel-apprenticeship-rachel-by-pettus-1865-1867:
    type: enslavement
    participants:
      - person: person-john-pettus
        role: enslaver
      - person: person-rachel
        role: enslaved_person
    start_event: event-rachel-apprenticed-1865
    end_event: event-rachel-released-1867
    properties:
      legal_status: apprenticeship
      description: "Rachel, freed at emancipation, bound back to her former enslaver's son by the Campbell County court on 1865-11-04 as an 'apprentice'; the Freedmen's Bureau secured her release on 1867-03-12."

Indentured servitude

Indentured servitude — most commonly a fixed-term labor contract exchanged for passage to the colonies — is modeled with the same relationship type, distinguished by legal_status: indentured. The start_event/end_event references the indenture instrument and the discharge:

relationships:
  rel-indenture-mary-by-burwell-1685-1692:
    type: enslavement
    participants:
      - person: person-richard-burwell
        role: enslaver
      - person: person-mary-cooper
        role: enslaved_person
    start_event: event-mary-indentured-1685
    end_event: event-mary-discharged-1692
    properties:
      legal_status: indentured
      description: "Seven-year indenture binding Mary Cooper to Richard Burwell of Gloucester County, Virginia, in exchange for passage from Bristol; discharge with freedom dues recorded in the county court order book on 1692-09-15."

The debt_bondage legal status follows the same shape — start_event references the debt acknowledgement that initiated the servitude, and end_event references the manumission, satisfaction-of-debt order, or death that closed it.

Archive-local event types

The events bounding enslavement relationships — sale/purchase, manumission, apprenticeship_binding/apprenticeship_released, indenture_signed/indenture_discharged — are not part of the standard event-types vocabulary. Archives should add them to archive-local event_types following the additional-event-types extension pattern, at which point references like type: sale in the examples above validate cleanly. Whether to elevate any of these to the standard vocabulary is a separate question tracked outside this section.

Source provenance

Source provenance for enslavement relationships (bills of sale, estate inventories, tax lists, manumission deeds) uses the standard Citation → Source → Repository chain. No relationship-level field encodes the source type — citations carry that, and the same enslavement relationship may be attested by multiple citations as additional records surface.

Further reading

The GLX project does not endorse a specific reconciliation methodology. The following projects provide controlled vocabularies and best-practice guidance for documenting enslaved persons that archives may wish to consult:

• Enslaved.org — Peoples of the Historical Slave Trade
• Beyond Kin — Documenting enslaved ancestors in family tree software
• See also Enslaved Persons Research in the GLX use-case guide for additional ethical framing.

Possibly Same Person

When two person records may describe the same individual but the identification cannot yet be confirmed, link them with a possibly_same_person relationship. Both participants are equal "candidates", so no role is set:

relationships:
  rel-maybe-john-1850-1860:
    type: possibly_same_person
    participants:
      - person: person-john-smith-1850-census
      - person: person-john-smith-1860-census
    notes: "Same name, similar age, same county. No primary record links them."

# Confidence and evidence go on a companion assertion, not the relationship.
assertions:
  assertion-john-1850-1860-match:
    subject:
      relationship: rel-maybe-john-1850-1860
    confidence: medium
    status: speculative
    citations:
      - citation-1850-census-page-12
      - citation-1860-census-page-47
    notes: |
      Both records list "John Smith" born ~1820 in Yorkshire, both in
      Leeds parish. No marriage or death record yet links them as the
      same person; needs further research in parish registers.

Note: most relationships connect two distinct people. The possibly_same_person type is the unusual case where the two participants are two records that may, on further research, turn out to refer to a single individual. Once the identification is confirmed (or refuted), follow-up actions are research decisions outside the scope of GLX — typically merging the records or recording the disproof on the assertion's status field. See Assertion Entity for the evidence model and Confidence Levels for the standard vocabulary. There is no direct GEDCOM mapping (see GEDCOM Mapping).

Participants Format

The participants array defines the people involved in the relationship and their roles:

Participant Object Fields

Field	Type	Required	Description
person	string	Yes	Reference to Person entity
role	string	No	Role from participant-roles vocabulary
properties	object	No	Per-participant properties (validated against relationship_properties vocabulary)
notes	string | string[]	No	Notes about this participant

participants:
  - person: person-john-smith
    role: spouse
    notes: "Groom"
  - person: person-mary-jones
    role: spouse
    notes: "Bride"

Per-Participant Properties

When participants in a relationship need individual data (e.g., age at marriage, legal status), use the properties field on each participant entry:

relationships:
  rel-marriage-john-mary:
    type: marriage
    participants:
      - person: person-john-smith
        role: spouse
        properties:
          description: "Widower at time of marriage"
      - person: person-mary-jones
        role: spouse
        properties:
          description: "First marriage"
    start_event: event-marriage-1875

Per-participant properties use the same vocabulary as relationship properties (relationship-properties.glx) and are validated against it. This is the same pattern used for event participant properties.

Participant Roles

Participant roles (spouse, parent, child, etc.) are defined in the archive's vocabularies/participant-roles.glx file.

See Vocabularies - Participant Roles for:

• Complete list of standard participant roles
• How to add custom roles
• Vocabulary file structure and examples
• Which roles apply to events vs. relationships

Validation Rules

• Relationship type must be from the relationship types vocabulary
• participants array must contain at least 2 participants
• All person references must point to existing Person entities
• Participant roles should be from the participant roles vocabulary (unknown roles generate warnings)
• If start_event or end_event is specified, it must reference an existing Event entity

File Organization

Note: File organization is flexible. Entities can be in any .glx file with any directory structure. The example below shows one-entity-per-file organization, which is recommended for collaborative projects (better git diffs) but not required.

Relationship files are typically stored in a relationships/ directory:

relationships/
├── rel-marriage-001.glx
├── rel-marriage-002.glx
├── rel-parent-child-001.glx
├── rel-parent-child-002.glx
├── rel-adoption-001.glx
└── rel-godparent-001.glx

GEDCOM Mapping

Relationships map to GEDCOM family and individual structures:

GLX Relationship Type	GEDCOM Tag	Notes
marriage	FAM record	Family with MARR event
parent_child	FAM.CHIL + INDI.FAMC	Child link to family (no PEDI or PEDI unknown)
biological_parent_child	FAM.CHIL + INDI.FAMC with PEDI birth	Biological child relationship
adoptive_parent_child	FAM.CHIL + INDI.FAMC with PEDI adopted	Legally adopted child (use adoption event for ADOP tag)
foster_parent_child	FAM.CHIL + INDI.FAMC with PEDI foster	Foster care relationship
sibling	Shared FAM.CHIL	Siblings share parents
possibly_same_person	(none)	No direct mapping. GEDCOM ALIA asserts identity, which is stronger than "possibly" — exporting an unconfirmed match would misrepresent the evidence.

PEDI (Pedigree Linkage):

The PEDI tag in GEDCOM 5.5.1 specifies the type of parent-child relationship. During import, PEDI values are mapped to specific relationship types:

• PEDI birth → biological_parent_child
• PEDI adopted → adoptive_parent_child
• PEDI foster → foster_parent_child
• PEDI unknown or missing → parent_child (generic)
• PEDI sealed (LDS) → parent_child (not specifically modeled)

This allows GLX to preserve the distinction between biological, adoptive, and foster relationships that is critical for accurate genealogical research.

Schema Reference

See relationship.schema.json for the complete JSON Schema definition.

See Also

• Person Entity - Entities connected by relationships
• Event Entity - Events that start/end relationships
• Core Concepts - Overview of vocabulary system