Contributing Sources

The conclusions about events and relationships of a person in Family Tree should be based on reliable, documented facts and sources. The value of Family Tree is that sources are provided as evidence to support the conclusions made by the community of users. FamilySearch provides a Sources resource to help establish and maintain integrity in the FamilySearch Family Tree.

Source References and Descriptions

Sources are used to show evidence of an event that occurred in the life of a person or for other information about a person. You can reference digital artifacts as sources that contain evidence about a person’s life. People and relationship objects in FamilySearch have a sourceReferences property that contains a list of references to sources which point to descriptions of sources which point to the actual source artifacts. The source descriptions describe the digital artifacts that they represent.

Source Tags

Each source reference has a tags property that is a list of tags for conclusions about a person, such as birth, death, name, and gender. These tags indicate which facts are verified by the sources being referenced. Tags help you quickly see which information about the person is cited in a source.

Relevant Source Properties

The properties of a source include a title, citation, notes, and a URI. The URI indicates the type of source. The source is either a records source or a memories source. The URI of a records source resolves to a persona. If the URI resolves to a memory, then the source is a memories source which refers to a memory that has been uploaded to the FamilySearch Family Tree. Records and memories sources receive special status and enable some extra features in the FamilySearch Family Tree app, such as being able to see a thumbnail version of a memory.

The Source Box

The FamilySearch Source Box is a tool that users can leverage to organize sets of source descriptions. Each user has a single source box. The source box is a container for a set of folders. Each folder is identified by a name and contains references to source descriptions. The source box always contains at least one folder, the "default folder", that can be identified by virtue of the fact that its name is the empty string. Other folders may be added and deleted from a user's source box, but the default folder may not be renamed nor deleted.

Each folder contains a set of references to source descriptions. When a Source Description is created, a reference to it is added to the default folder of the user who created the description.

References to source descriptions can be added or removed from folders, but a reference to any given source description may not be contained in more than one folder. This means that adding a reference to a source description to one folder may also have the effect of removing it from another folder.

A reference to a source description can be removed from all folders. In other words, not all source descriptions created by a user have to be contained in the user's source box. Note that removing a reference to a source description from a folder in a source box does not remove the source description.

  • To see a specific user's list of folders in the user's source box, use the User Source Folders resource.
  • To create a new folder, use the Source Folders resource.
  • To read, edit, or delete a folder, use the Source Folder resource.
  • To page through the descriptions contained in a specific folder, or to add a description reference to a folder, use the Source Folder Source Descriptions resource.
  • To read a list of all source descriptions contained in all folders of a specific user, use the User Source Descriptions resource.

Objectives of Family Tree Sources

The following are the major objectives and goals relating to Family Tree sources:

  1. Family Tree data quality will directly correlate to good user experiences.
  2. Partner app users will contribute quality Family Tree sources. A primary objective of the partner initiative is to have users of partner products contribute quality data to Family Tree.
  3. Replication of Family Tree sources will not be allowed to degrade data integrity. Data that is captured by one system can be returned or accessed by another system with no loss or corruption of data. For instance, if a partner reads a Family Tree source then later writes it back to Family Tree, the data and references to that source should remain the same.
  4. New Family Tree sources will not create duplicates. This requirement exists to prevent the creation of redundant sources. Duplication is confusing to the user. It presents clutter in the UI. Today we are experiencing issues with lots of sources on a person. This duplication hampers or prevents our ability to judge quality of sources, and may impact the ability to support hints.
    • A Family Tree person source must not be duplicated (look the same to the user) on that same Family Tree person.
    • A Family Tree person source that is represented on a partner site must show the same info as that source in Family Tree if the user will be initiating writes to that Family Tree person.

Good Programming Practices

Apps can influence good source usage behavior by meeting FamilySearch Certification requirements and by encouraging source use with the following features:

  • Create Person and Adding Vital Events
  • Create Source
  • Attach Source
  • Edit Source
  • Detach Source
  • Delete Source
  • Compare (“Push-Pull”) Sources

Apps should recognize duplicate sources on a person and prevent a duplicate source from being created and attached to the same person. Duplicate sources have the following characteristics:

  • The same SrcID (Users can push-pull source conclusions).
  • All the exact same source fields.

Source Objects

The platform API data objects for sources are SourceDescription and SourceReference. For an overview of all Family Tree data objects, see GEDCOM X Data Objects in Family Tree.

Each person has fields that are conclusions such as name, birth date, gender, and so forth. Each conclusion has a value, reason, and contributor that are shown in the source ChangeHistory. Sources can be provided to support conclusions.

SourceDescription Fields

  • Title. The name of the source, always required.
  • URL. A URL to the record or evidence or uploaded photo.
  • Citation. Where the record can be found.
  • Note. Notes the user can provide describing the record or data in the record. For example, indexed or transcribed information.
  • Internal SrcId. Identifies the source.
  • Internal SrcType.
    • World icon. A custom source that is fully editable.
    • FamilySearch tree icon. A FamilySearch locked record source. The Title, URL, and Citation are provided by FamilySearch. The Note is editable.
    • Album icon. A FamilySearch document or photo source. The URL to a FamilySearch document.

Note The properties of SourceDescription are limited by number of characters. To read the current limits see the links properties configuration. You must be logged in to see the links properties configuration.

SourceReference Fields

  • Reason. Why the source is attached to the person.
  • Tags. Vital statistics (such as name and birth) fields that are tagged to this source.
  • Internal pid. The person the source is attached to.
  • Internal SrcId. The source description that is attached to the PID.
Change Language


Feedback was sent.

Can't send feedback. Retry in 5 seconds.