Common GEDCOM Extensions

Editor:: John Cardinal (Family History Hosting, LLC)

Everyone is permitted to copy and distribute verbatim copies of this document, but changing it is not allowed.

Document Information
Abstract
Document Status
Subrecords with Custom Tag Names
Primitive Elements
Index

Document Information

Abstract

This document describes subrecords with custom tag names that appear in more than one popular genealogy program.

Document Status

This document is a Draft. Feedback and comments are welcome. You may create a pull-request to propose and collaborate on changes to the document. A future version of this document will remove its Draft status.

GitHub Project: GEDCOM-5.5.2
Public URL of Document: https://jfcardinal.github.io/GEDCOM-5.5.2/extensions.html
Associated documents: https://jfcardinal.github.io/GEDCOM-5.5.2

Subrecords with Custom Tag Names

_LOC Location Record, Location Link

See _PLAC.

_PLAC Place Record, Place Link

Several programs implement custom place records to share place metadata with two or more PLAC subrecords. This effectively creates a master list of places where common place metadata is specified only once. Place metadata typically includes latitude/longitude, multimedia references, and notes.

Programs that support place records typically allow all the subrecords that are valid under a PLAC subrecord as child records of a _PLAC record.

Family Historian

Family Historian uses the PLAC line_value as a key to find a _PLAC record. Family Historian assigns an ID to the _PLAC record, but the ID is not used as a pointer.

Family Historian uses a _PLAC subrecord to specify an additional place so an event may refer to two places, such as "from" and "to" places for an emigration event.

Example

1 EMIG
2 PLAC Ames, Iowa
2 _PLAC Parma, Ohio

...

0 @P1@ _PLAC Ames, Iowa
1 MAP
2 LATI N42.034722
2 LONG W93.62
0 @P2@ _PLAC Parma, Ohio
1 MAP
2 LATI N41.391944
2 LONG W81.728611

GEDCOM 5.5EL

The GEDCOM variant GEDCOM 5.5EL defines a _LOC record and subrecord. The records are linked using a GEDCOM ID and pointer. The _LOC record supports several subrecords, more than shown in the example below. _LOC records are arranged in a hierarchy, with a _LOC record for each level.

Example

1 DEAT
2 PLAC Ames, Iowa, United States
3 _LOC @L1@

...

0 @L1@ _LOC
1 NAME Ames
1 MAP
2 LATI N42.034722
2 LONG W93.62
1 _LOC @L2@
0 @L2@ _LOC
1 NAME Iowa
1 _LOC @L3@
0 @L3@ _LOC
1 NAME United States

For more details, see the GenWiki entry.

Legacy

Legacy uses the PLAC line_value as a key to find a _PLAC_DEFN record which has a matching PLAC subrecord.

Example

1 BIRT
2 PLAC Ames, Iowa, United States

...

0 _PLAC_DEFN
1 PLAC Ames, Iowa, United States
1 ABBR Ames, IA
1 MAP
2 LATI N42.034722
2 LONG W93.62

RootsMagic

RootsMagic uses the PLAC line_value as a key to find a _PLAC record.

Example

1 BIRT
2 PLAC Ames, Iowa

...

0 _PLAC Ames, Iowa
1 MAP
2 LATI N42.034722
2 LONG W93.62

_PRIM Primary or Preferred

_PRIM is used to indicate that its parent record is the primary or preferred instance.

n _PRIM <Y_OR_N>

0:1

For example, to indicate that an INDI.OBJE subrecord should be treated as the preferred multimedia item:

0 @I1@ INDI
1 OBJE
2 FILE c:\picture.jpg
3 FORM jpg
2 _PRIM Y

_PRIM is supported on input and/or output by:

Legacy Family Tree
RootsMagic
rootstrust

As shown in the example, a common use of _PRIM is to indicate a preferred multimedia record, but there are other uses.

_UID UUID

_UID is used to specify a Universally Unique Identifier (UUID) in string format.

n _UID <UUID>

0:1

For example, to indicate that an INDI has been assigned a UUID:

0 @I1@ INDI
1 _UID f81d4fae-7dec-11d0-a765-00a0c91e6bf6

While _UID is written by a long list of genealogy applications, formats are inconsistent. See the <UUID> Primitive Element for details.

_SDATE Sort Date

_SDATE specifies a sort date for an event. It uses the same value format as a DATE subrecord.

The value format Primitive Element is DMY.

n _SDATE <DMY>

0:1

_SDATE is used under the context of an event such as FAM.MARR or INDI.BIRT, etc. It allows the user to sort an event by a date that is different from the actual date of the event.

Example

0 @I1@ INDI
1 NAME John /Doe/
1 BIRT
2 DATE 1 JAN 1900
1 DEAT
2 DATE 1 JAN 1990
1 BURI
2 DATE 5 JAN 1990
1 OBIT
2 DATE 3 JAN 1990
2 _SDATE 6 JAN 1990

In the example above, the user enters a sort date for the OBIT (obituary) subrecord so that it sorts after the BURI (burial) subrecord even though the actual date of the obituary would place it before the burial.

_SDATE is supported on input and/or output by:

Family Historian (when using Export GEDCOM File plug-in)
RootsMagic
The Master Genealogist

_SHAR Co-Participant ID

_SHAR is used to add an individual to an event.

n _SHAR @<ID:INDI>@

0:M

_SHAR is used under the context of an event such as FAM.MARR or INDI.BIRT, etc.

The person indicated by the pointer should be added to the instance of the event which is the parent record of the _SHAR subrecord. The event should not be duplicated as a separate event for the co-participant; the intent is to share a single instance of the event so that:

Output from the event can reference all the participants.
Changes to a single event apply to all the participants.

_SHAR is often accompanied by an additional _ROLE subrecord to designate the role of the co-participant. For some roles, the meaning of the event applies to the co-participant. For other roles, the meaning of the event does not apply to the co-participant; the meaning is supplied by the role name only.

So, for example, a co-participant with the role "Principal" might be used to add a co-purchaser to an event that describes a land purchase by several individuals. The meaning of the event—purchased real estate—is applied to the person underwhich the event appears and also to the co-participant.

Conversely, a co-participant with the role "Best Man" might be used to add a person to a marriage event. The meaning of the event—was married—is not applied to the co-participant.

If no _ROLE (or equivalent) is supplied, or if the _ROLE value is unrecognized, the meaning of the event should not be applied to the co-participant. The co-participant should be treated as generically interested in the event without applying a specific meaning.

Example

0 @F1@ FAM
1 HUSB @I1@
1 WIFE @I2@
1 MARR
2 DATE 25 AUG 1945
2 _SHAR @I3@
3 _ROLE Maid of Honor
2 _SHAR @I4@
3 _ROLE Officiant

_SHAR is supported on input and/or output by:

Family Historian (when using Export GEDCOM plug-in)
Heredis
Legacy Family Tree
RootsMagic
rootstrust
The Master Genealogist

_ROLE Co-Participant Role

_ROLE is used to specify the role played by an individual in connection with an event.

n _ROLE <TEXT>

0:1

_ROLE is used under the context of a _SHAR subrecord or equivalent. See the _SHAR description for further details.

_ROLE is supported on input and/or output by:

Family Historian (_SHAR.ROLE when using Export GEDCOM plug-in)
Heradis (_SHAR.RELA)
Legacy (_SHAR.ROLE)
RootsMagic (USHAR.ROLE)
rootstrust (_SHAR.ROLE)
The Master Genealogist (_SHAR.ROLE)

As shown above, multiple applications use "ROLE" rather than "_ROLE".

Primitive Elements

UUID {Size=36:38}

A UUID is a Universally Unique Identifier in string format. A UUID is also known as a Globally Unique Identifier (GUID). A UUID is defined by RFC4122.

The Internet Engineering Task Force defines the string format of the UUID as 32 hexadecimal digits separated by hyphens into 6 segments with lengths 8, 4, 4, 4, 12, respectively. That format is the preferred value.

UUIDs are only used in custom subrecords, and the format was not defined by a GEDCOM specification. Early adopters did not use the RFC4122 format. THese are the common formats:

RFC4122 format (preferred):
12345678-1234-1234-1234-123456789abc
PAF-inspired format with checksum:
12345678123412341234123456789abc1234
Microsoft-inspired format with braces:
{12345678-1234-1234-1234-123456789abc}

PAF Checksum Calculation

The following C# method computes a four character hexadecimal checksum value according to the algorithm used by PAF.

/// <summary>
/// Returns a 4-hex digit checksum computed from a UUID string.
/// Follows the PAF algorithm.
/// </summary>
/// <param name="uuid">String containing 32 hexadecimal
/// characters, no hyphens or other characters.</param>
/// <returns>A 4 character string of hex digits.</returns>
public string GetPafChecksum(string uuid) {
    const int kUuidLength = 32;
    const int kFromBase = 16;
    const int kDigitsPerByte = 2;

    if (string.IsNullOrEmpty(uuid) || uuid.Length != kUuidLength) {
      throw new ArgumentException(
        String.Format("{0} is not {1} characters long",
          nameof(uuid), kUuidLength
        )
      );
    }

    byte sumA = 0;
    byte sumB = 0;

    for (int index = 0; index < uuid.Length; index += kDigitsPerByte) {
      byte value = Convert.ToByte(
        uuid.Substring(index, kDigitsPerByte), kFromBase);
      sumA += value;
      sumB += sumA;
    }
    return sumA.ToString("X2") + sumB.ToString("X2");
}

See: _UID

Y_OR_N {Size=1:1}

A one-character keyword that indicates yes or no via the abbreviations "Y" (U+0059) or "N" (U+004E), respectively.

The meaning of the value is determined by the context.

See: _PRIM

Contents

Document Information

Abstract

Document Status

Subrecords with Custom Tag Names

Family Historian

GEDCOM 5.5EL

Legacy

RootsMagic

Primitive Elements

PAF Checksum Calculation

Index