Names

June 29, 2023

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. Family Tree data is intended to following industry best practices for languate encoding, so if this guide does not have sufficient detail, please refer to the BCP 47 Spec regarding name language tags.

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

When not provided, the name type will default to http://gedcomx.org/BirthName.

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).

Currently, the following languages can be expected on name forms in the FamilySearch Family Tree. If no language is specified, the name form is assumed to be a generic Latin-based form.

es (Spanish)
ja (Japanese)
ja-Latn (Japanese, Romanized)
ja-Hani (Japanese, Kanji)
km (Khmer)
km-Latn (Khmer, Romanized)
ko (Korean)
ko-Latn (Korean, Romanized)
ko-Hani (Korean, Hanja)
mn-Latn (Mongolian, Romanized)
mn-Cyrl (Mongolian, Cyrillic)
pt (Portuguese)
ru-Latn (Russian, Romanized)
ru-Cyrl (Russian, Cyrillic)
th (Thai)
th-Latn (Thai, Romanized)
und-Hani (Han, Unspecified Language)
und-Cyrl (Cyrillic, Unspecified Language)
vi (Vietnamese)
vi-Latn (Vietnamese, Romanized)
x-Latn (Generic Latin)
zh-Latn (Chinese, Romanized)
zh-Hani (Chinese, Han)

Family Tree is undergoing an effort to support additional name forms and normalize the existing set. This effort will be incremental and ongoing with no specific timeframe. The set is expected to look like this:

sq (Albanian)
hy (Armenian)
hy-Latn (Armenian, Romanized)
bg (Bulgarian, Cyrillic)
bg-Latn (Bulgarian, Romanized)
zh (Chinese)
zh-Hani (Chinese)
zh-Latn (Chinese, Romanized)
hr (Croatian)
cs (Czech)
da (Danish)
nl (Dutch)
en (English)
et (Estonian)
fj (Fijian)
fi (Finnish)
fr (French)
de (German)
el (Greek)
el-Latn (Greek, Romanized)
ht (Haitian)
hu (Hungarian)
is (Icelandic)
id (Indonesian)
it (Italian)
ja (Japanese)
ja-Hrkt (Japanese, Kana)
ja-Latn (Japanese, Romanized)
km (Khmer)
km-Latn (Khmer, Romanized)
ko-Hang (Korean, Hangul)
ko-Hani (Korean, Hanja)
ko-Latn (Korean, Romanized)
lv (Latvian)
lt (Lithuanian)
mk (Macedonian, Cyrillic)
mk-Latn (Macedonian, Romanized)
ms (Malay)
mn-Cyrl (Mongolian, Cyrillic)
mn-Latn (Mongolian, Romanized)
no (Norwegian)
pl (Polish)
pt (Portuguese)
ro (Romanian)
ru (Russian)
ru-Latn (Russian, Romanized)
sm (Samoan)
sr-Cyrl (Serbian, Cyrillic)
sr-Latn (Serbian, Romanized)
sk (Slovak)
sl (Slovenian)
es (Spanish)
sv (Swedish)
th (Thai)
th-Latn (Thai, Romanized)
tr (Turkish)
uk (Ukrainian)
uk-Latn (Ukrainian, Romanized)
vi (Vietnamese)

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.

Note 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 a preferred name yet.	Create an alternate name.

To "promote" an alternate name to become preferred is not straightforward — first you must 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.