Person Entity

← Back to Entity Types

Overview

The Person entity represents an individual in the family archive. Person entities can be stored in any .glx file in the repository under the persons key.

File Format

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

# Any .glx file (commonly in persons/ directory)
persons:
  person-john-smith-1850:
    properties:
      name:
        value: "John Smith"
        fields:
          given: "John"
          surname: "Smith"

Key Points:

• Entity ID is the map key (person-john-smith-1850)
• 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)

Optional Fields

Field	Type	Description
properties	object	Vocabulary-defined properties (name, gender, dates, etc.)
notes	string	Free-form notes about the person

Note: While no properties are technically required, the name property is recommended for most person records as it enables meaningful identification and display.

Entity ID (map key)

• Format: Any alphanumeric string with hyphens, 1-64 characters
• Must be unique within the archive
• Example formats:
  • Descriptive: john-smith-1850, mary-jones
  • Random hex: a1b2c3d4
  • Prefixed: person-a1b2c3d4
  • Sequential: 001, 002

properties

• Type: Object
• Required: No
• Description: Vocabulary-defined properties representing the concluded/accepted values for this person

Structure:

properties:
  name:                      # Unified name property with optional fields
    value: String           # Full name as recorded
    fields:                 # Optional structured breakdown
      type: String          # Name classification (birth, married, alias, etc.)
      prefix: String
      given: String
      nickname: String
      surname_prefix: String  # e.g., von, van, de
      surname: String
      suffix: String
  gender: String            # From person_properties vocabulary
  born_on: Date            # From person_properties vocabulary
  born_at: "place-id"      # From person_properties vocabulary (reference)
  died_on: Date            # From person_properties vocabulary
  died_at: "place-id"      # From person_properties vocabulary (reference)
  occupation: String        # From person_properties vocabulary
  residence: "place-id"    # From person_properties vocabulary (reference)

Example:

properties:
  name:
    value: "John Smith"
    fields:
      given: "John"
      surname: "Smith"
  gender: "male"
  born_on: "1850-01-15"
  born_at: "place-leeds"
  died_on: "1920-06-20"
  died_at: "place-london"
  occupation: "blacksmith"
  residence:
    - value: "place-leeds"
      date: "FROM 1850 TO 1900"
    - value: "place-london"
      date: "FROM 1900 TO 1920"

Gender Property

The gender property is constrained by the gender_types vocabulary via vocabulary_type: gender_types. The standard vocabulary includes male, female, unknown, and other (with GEDCOM SEX mappings), but archives may extend it with additional entries. Values not found in the vocabulary produce a warning, not an error — this allows archives to use custom values before adding them to the vocabulary. The property is temporal, allowing changes to be recorded over time.

Temporal Property Examples

Properties marked as temporal: true can hold multiple values. Dates are optional — use them when you know when each value applied, omit them when you don't.

Occupation Changes:

properties:
  occupation:
    - value: "farm laborer"
      date: "1865"
    - value: "blacksmith apprentice"
      date: "FROM 1867 TO 1870"
    - value: "blacksmith"
      date: "FROM 1870 TO 1890"
    - value: "farmer"
      date: "FROM 1890 TO 1920"

Occupations Without Dates (e.g., from an obituary):

properties:
  occupation:
    - value: "teacher"
    - value: "school principal"
    - value: "county superintendent"

Name Changes (e.g., marriage):

properties:
  name:
    - value: "Mary Jones"
      date: "FROM 1855 TO 1880"
      fields:
        given: "Mary"
        surname: "Jones"
    - value: "Mary Smith"
      date: "FROM 1880"
      fields:
        given: "Mary"
        surname: "Smith"

Name Variation Examples

The type field on name entries distinguishes why multiple names exist. Use it not just for temporal changes (birth to married) but also for alternate spellings, abbreviations, and names as recorded in specific documents.

The authoritative list of name type values is defined in the person properties vocabulary. The table below highlights common values and how to use them.

Common name type values:

Type	Usage
birth	Name at birth
married	Name after marriage
maiden	Name used before marriage (typically pre-marriage surname)
alias	Known alternate identity
aka	Also known as (general alternate name)
immigrant	Name used when immigrating
anglicized	Anglicized or localized form of a foreign name
religious	Name taken for religious purposes
formal	Formal or legal name
professional	Professional or stage name
as_recorded	Name exactly as it appears in a source document

Alternate Spellings and Abbreviations:

properties:
  name:
    - value: "Robert Webb"
      fields:
        type: "birth"
        given: "Robert"
        surname: "Webb"
    - value: "R. Webb"
      fields:
        type: "as_recorded"
        given: "R."
        surname: "Webb"

Anglicized Name:

properties:
  name:
    - value: "Johann Schmidt"
      fields:
        type: "birth"
        given: "Johann"
        surname: "Schmidt"
    - value: "John Smith"
      date: "FROM 1885"
      fields:
        type: "anglicized"
        given: "John"
        surname: "Smith"

Multiple Known Aliases:

properties:
  name:
    - value: "William Henry McCarty"
      fields:
        type: "birth"
        given: "William Henry"
        surname: "McCarty"
    - value: "William H. Bonney"
      fields:
        type: "alias"
        given: "William H."
        surname: "Bonney"
    - value: "Billy the Kid"
      fields:
        type: "aka"

Tip: Dates are optional on name entries. Use them when you know when a name was adopted; omit them for variations that aren't tied to a specific time period. The type field clarifies why each entry exists without implying temporal succession.

Multiple Residences:

properties:
  residence:
    - value: "place-leeds"
      date: "FROM 1850 TO 1870"
    - value: "place-manchester"
      date: "FROM 1870 TO 1885"
    - value: "place-london"
      date: "FROM 1885 TO 1920"

Nationality/Citizenship Changes:

properties:
  nationality:
    - value: "British Subject"
      date: "FROM 1850 TO 1895"
    - value: "American Citizen"
      date: "FROM 1895"

See Also: Temporal Properties Example for a complete working archive demonstrating temporal values with assertions and evidence chains.

Key Points:

• All properties are optional
• Property names and types are validated against the person_properties vocabulary
• Properties can be temporal (change over time) - see Core Concepts - Data Types
• Custom properties can be added by extending the vocabulary
• Whether a person is living or deceased is implied by the presence/absence of died_on

Usage Patterns

Basic Person

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

Person with Full Details

# persons/person-margaret-smith.glx
persons:
  person-margaret-smith-1825:
    properties:
      name:
        value: "Margaret Eleanor Smith"
        fields:
          given: "Margaret Eleanor"
          surname: "Smith"
      gender: "female"
      born_on: "1825-04-10"
      died_on: "1890-11-22"
    notes: |
      Family tradition says she was named after her grandmother.
      Need to verify with census records.

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.

Person files are typically stored in a persons/ directory:

persons/
├── person-john-smith.glx
├── person-mary-jones.glx
├── person-margaret-smith.glx
└── person-thomas-brown.glx

GEDCOM Mapping

GLX Field	GEDCOM Tag	Notes
Entity ID (map key)	@INDI@	Individual record ID
properties.name	INDI.NAME	Person's name
properties.name.fields.given	INDI.NAME.GIVN	Given name
properties.name.fields.surname	INDI.NAME.SURN	Surname
properties.gender	INDI.SEX	M/F mapped to male/female
properties.born_on	INDI.BIRT.DATE	Birth date
properties.born_at	INDI.BIRT.PLAC	Birth place (reference)
properties.died_on	INDI.DEAT.DATE	Death date
properties.died_at	INDI.DEAT.PLAC	Death place (reference)
properties.occupation	INDI.OCCU	Occupation
properties.residence	INDI.RESI	Residence
notes	INDI.NOTE	Notes

Note: GEDCOM stores birth/death as events with dates and places. GLX imports these as person properties for convenience, while the full event details are preserved in Event entities.

Validation Rules

• Properties should be from the person properties vocabulary (unknown properties generate warnings)
• All place references must point to existing Place entities
• Date formats must follow genealogical date conventions

Schema Reference

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

See Also

• Event Entity - Life events for this person
• Relationship Entity - Connections to other people
• Assertion Entity - Evidence for person properties
• Core Concepts - Data Types - Date and property formats
• Vocabularies - Person properties vocabulary