The Family Tree Data Model

June 29, 2023

The purpose of this document is to help programmers become familiar with the data model of the FamilySearch Family Tree. The FamilySearch data model conforms to the GEDCOM X spec as much as possible. For more information, see the GEDCOM X guide.

The following graphic shows how data objects used in the FamilySearch Family Tree are associated. As the model illustrates, the core of the Family Tree data model are the individual persons that, linked together by relationships, create the Tree. The purpose of the other data objects is to give support and detailed information about the person, relationships and the research recorded in the Family Tree.

Persons

Each person in the Family Tree has details that identify the person, the research done on the person, the family relationships of the person, contributors to facts about the person, and memories of the person.

The model as applied to a Family Tree person provides the following data associations:

• Links to other resources of information relevant to the person.

• Vital statistics about the person.

• Other facts about the person.

  • Fact details for each type of fact. See the Facts documentation.

• Relationships of couples and parents-to-children

• Source References

• SourceDescriptions

• Contributors

• PlaceDescriptions

• Discussions

• Memories

• Changes

• Notes

  

Relationships

Family relationships in the Family Tree consist of two types of relationships: a couple relationship and a child-and-parents relationship. FamilySearch has a Child-and-Parents Relationship resource and a Couple Relationship resource to establish and maintain relationships. A couple relationship is between two people and can be read, updated, or deleted using the Couple Relationship resource. A child-and-parents relationship is between a child and two parents and can be read, updated or deleted using the Child-and-Parents Relationship resource. There are no other relationship types in FamilySearch.

The child-and-parents relationship is a description of the relationship between a child and two parents. This relationship governs the relationship between a child and the child's parents, that is, parent 1 or parent 2 or both parents, with the possibility that one of the parents is not specified. The child-and-parents relationship may contain facts describing the lineage type between the child and each parent. Examples of lineage types include biological, adopted, guardianship, step, etc.

Relationships consist of source references and descriptions, place descriptions, discussions, memories, changes, and notes. The family relationships data objects for a person in the Family Tree include the following:

• A couple relationship object of each person.
• A child-and-parent relationship object for each person.
• Notes and changes objects.

For more detail on family relationships in Family Tree, see the Pedigree guide.

Discussions

A discussion object has references to user-contributed comment objects. Discussion objects are identified in a discussion reference object which is associated with a person. (You can create a person object in the Family Tree by using the POST function of the Persons resource. For details, see the Create Person example of the Persons resource.) A person can have many discussion references and a discussion reference can have more than one comment. For more information on performing discussion operations, see the Discussions resource.

Memories

A memory is a container for user-contributed artifacts, such as photos, stories, documents and audios. Memory persona objects are created to identify people who are part of a memory. Personas are then identified in a memory reference object which is associated with a person. Memories can also have comment objects attached to them.

For more details on memories and how to create and associate them with a person, see the Memories guide.

Sources

Sources are information that supports conclusions about a person or relationship in the Family Tree. Sources are stored in collections, and users each have a source box that can be used to help organize and manage research they do. For more information on sources and source boxes, see the Sources guide.

A source reference object is created to associate sources with a person or relationship in the Family Tree.