Names

In Family Tree, people have one preferred name, although a person may have multiple alternate names. Names have a type, a list of name forms, and a preferred flag.

The type for a name is optional. Four name types are supported:

  • http://gedcomx.org/AlsoKnownAs
  • http://gedcomx.org/BirthName
  • http://gedcomx.org/MarriedName
  • http://gedcomx.org/Nickname

Name forms provide a way to document multiple versions of a name, specifically in different languages. A name must have at least one name form. Name forms include a language (optional), the full text of the name (required), and a list of name parts (at least one name part is required).

Name parts have a type and a value. Four name part types are supported:

  • http://gedcomx.org/Prefix
  • http://gedcomx.org/Suffix
  • http://gedcomx.org/Given
  • http://gedcomx.org/Surname

Only one instance of each name part type can exist. For example, if you provide two http://gedcomx.org/Given parts, the second one will be ignored.

This example demonstrates the correct way to create a name with multiple name forms. Notice that it is the same name presented in three different language scripts. Note also that the given name part may contain multiple name pieces.

{
  "type": "http://gedcomx.org/BirthName",
  "preferred": true,
  "nameForms": [
    {
      "lang": "ru-Cyrl",
      "fullText": "Пётр Ильи́ч Чайко́вский",
      "parts": [
        {
          "value": "Пётр Ильи́ч",
          "type": "http://gedcomx.org/Given"
        },
        {
          "value": "Чайко́вский",
          "type": "http://gedcomx.org/Surname"
        }
      ]
    },
    {
      "lang": "ru-Latn",
      "fullText": "Pyotr Ilyich Tchaikovsky",
      "parts": [
        {
          "value": "Pyotr Ilyich",
          "type": "http://gedcomx.org/Given"
        },
        {
          "value": "Tchaikovsky",
          "type": "http://gedcomx.org/Surname"
        }
      ]
    },
    {
      "lang": "en-Latn",
      "fullText": "Peter Ilyich Tchaikovsky",
      "parts": [
        {
          "value": "Peter Ilyich",
          "type": "http://gedcomx.org/Given"
        },
        {
          "value": "Tchaikovsky",
          "type": "http://gedcomx.org/Surname"
        }
      ]
    }
  ]
}

Preferred vs Alternate Names

The preferred name and alternate names are distinct data types. A person must have a preferred name, and can only ever have one preferred name, typically the birth name. A person may have zero or many alternate names.

! Using "or" in a name, such as "Joe or Joey," is discouraged. Use either a preferred or an alternate name.

The preferred name can only be updated (but never deleted). Because there is always one and only one preferred name, the ID of the preferred name is not required to be specified when updating it; a check to see whether the preferred flag is set to true is sufficient.

When updating and creating names, four situations based on two conditions are possible:

  • Was an ID provided?
  • Is the preferred flag set to true?
Preferred Not Preferred
ID Update the preferred name. An error is thrown if the ID matches an alternate name. Update the alternate name. An error is thrown if the ID matches a preferred name.
No ID Update the preferred name, or create it if the person is being created and doesn't have an alternate name yet. Create an alternate name.

To "promote" an alternate name to become preferred is not straightforward — first you have to create an alternate name to match the current preferred value, next update the preferred name to match the alternate name you want to be preferred, and then delete the alternate name you just promoted.

! These rules apply only to deceased persons. Updating and creating names for living persons will exhibit a different behavior.