Contributing to the FamilySearch Family Tree

Source Center Open Edit (SCOE)standards

The FamilySearch Family Tree is intended to provide “One complete, accurate record for each person who has lived on the earth.” The Family Tree holds conclusions such as dates, names, places, memories, sources, and so forth about people and relationships. The Family Tree is a single tree, not a collection of private user trees.

The Family Tree model borrows heavily from Internet models of collaboration, such as wikis. FamilySearch is an online app that allows you to collaborate, learn, build, source, share, and preserve your family history with others online.

FamilySearch Historical Records collections include information such as births, marriages, deaths, censuses, immigrations, military service, and probate which may be referenced as evidence of conclusions but are not included in Family Tree person searches. These conclusions can be private or public, read-only or editable, on paper, hard drive, or in the cloud.

A public, collaborative, online tree such as Family Tree provides the following benefits:

• Reduces duplication
• Divides labor
• Converges towards accuracy
• Preserves our work

The Family Tree has the following defining characteristics:

• Public accessibility. Anyone can access the information in Family Tree. However, temple ordinance data is only available to members of The Church of Jesus Christ of Latter-day Saints.
• Source centricity. The conclusions about relationships in Family Tree are based on reliable, documented facts and sources. The center or foundation of Family Tree is that it consists of sources as evidence that support the conclusions made by the community of users.
• Openly editable. Anyone can add, update, and delete the content and relationships in the Family Tree.

Good Contributing User Behavior

The quality of the Family Tree data is largely dependent upon voluntary and in some cases enforced practices. We encourage those who are involved in the genealogical process as contributors to Family Tree to consider the following guidelines.

Contribute to Improve

• Change information only if your conclusion is more correct.
• Provide research notes and digital sources such as pictures, documents, recordings and more.
• Provide reasons that will make it easy for other contributors to reach correct conclusions.
• Provide standardized dates and places when possible.
• Check for duplicates when adding new persons.

Maintain as You Go

• Fix data you know is incorrect.
• Remove data only when necessary.
• Rarely delete people unless you created them. Deleting a relationship is more frequently the correct action.

Converge Information Quality

• Do not introduce duplication.
• Merge duplicate persons or set Not a Match if it is not the same person.
• Resolve conflicting information wherever possible. Show conflicts to users and encourage users to resolve conflicts. Conclusions should be made by individuals not by computers.

Watch for Changes

• Watch person records for changes.
• When erroneous changes occur, restore to the correct values and give the reason why the restored value is correct.

Good Programming Practices

Apps can encourage good community behavior by meeting FamilySearch Compatibility requirements.

Apps that write to Family Tree can help users follow good behaviors by including features in the following areas:

• Show Information
• Change Conclusions
• Add or Edit People
• Update a Source
• Compare Persons
• Copy Person Records
• Crawl the Family Tree
• Match Person Records
• Resolve Duplicates (Merge)
• Watch and Notify for Changes

Showing Information

Person detail pages should show a summary of discussions, sources, memories, family relationships, and vital information. Provide buttons or links to easily add or make changes.
Example Person Details Page

Note All data in the Family Tree is open to all users except Temple Ordinance data which is only available to members of The Church of Jesus Christ of Latter-day Saints.

Changing Conclusions

• Before making a change to conclusions of vital information, relationships, or sources for a person in the Family Tree, display the following information:
  • Current value
  • Current contributor contact name
  • Last change date
  • The reason for the last change made
  • Tagged sources
• Prompt the user to enter the current reason before any changes are committed. A reason is not needed when adding a person that is completely new to the Family Tree.
• Provide for the following actions: 
  • Merges and un-merges
  • Relationship additions and changes
  • Source attachments and detachments
  • Discussion thread participation
  • Ability to contact a contributor
  • Ability to restore prior change history items
• Some conclusions can be deleted but name, gender, and death, cannot be deleted. The date, place, and reason values contained within the conclusion can be deleted, but these conclusions cannot.

Add or Edit People

• Make sure users know when they are editing data in the Family Tree as opposed to the tree in their own app.
• Copying or uploading people to the Family Tree must always be done by a user one person at a time unless matching is being used. Do not allow mass editing or automatic updates on person records.
• If high-confidence matches are null for multiple persons, the addition of these persons to the Family Tree can be batched.
• Users must be given the opportunity to compare the app tree values with the Family Tree values on an item by item basis. Prior contributor reasons, names, and dates should also be provided.
• If there is a modification or deletion of any Family Tree value, encourage the contributor to enter a reason for making the change.
• If it is discovered that the person being pushed does not yet exist in the Family Tree, then each vital conclusion for that person may be added to a new person in Family Tree without a reason.
• Maintain as much of the data and metadata as needed so that data can be resubmitted to the Family Tree if needed without data loss, duplication, or corruption. That is, keep the person data in your app tree as well.
• When it appears that a person record from your app does not already exist in Family Tree, you can create that person in Family Tree. See the Persons explanation and the Create Person example.
• When creating a new person record, your app should also create relationship records that tie the newly created person to other persons.

Add, Edit or Delete Person Notes

Multiple notes can be added to a person. There are no notes for person facts or events. There is no restriction on the editing or deletion of these notes. The application may be designed to only allow the modification of notes created by the user. However, any note contributed by anybody can be changed by anybody but a entry of the reason for the change or deletion must be completed. Reasons are additive and cannot be changed. All note changes or deletions show up in the "Latest Changes" log.

• Reasons (or "changeMessage") must be requested when changes or deletions are made to an existing person notes.
• Use the Note IDs to update or replace note subject, text, or attribution.
• Though the system doesn't requrement unique titles, the application could check to avoid duplicate titles.

Update a Source

Sources play an important role in the collaborative nature of Family Tree. Provide the ability to read and create sources on Family Tree.

When your app attaches, modifies, or detaches sources, give users the opportunity to record a reason for the action. For actions that modify or detach a source, the existing reason should be available to the user, if a reason exists.

Compare Persons

Provide the ability to compare persons in your tree to persons in Family Tree. Assist users in moving data between trees.

Copy Person Records

• Maintain Data Integrity. Keep original data and metadata on hand while copying to allow recovery if the copy to Family Tree encounters errors.
• Respect Data Privacy. Do not expose data about living persons to persons who do not have permissions granted by FamilySearch to view the data. If your app tree environment allows sharing trees among multiple users, the records of the living persons obtained by one user must not be shared with unauthorized users.
• Establish a Link. When your app copies a person record to or from the Family Tree, establish a link in your tree to the FamilySearch person.

Crawl the Family Tree

Your app may traverse (crawl) the Family Tree beginning at the user’s person record. Your app may crawl up ancestral lines and down descendant lines. Allow the user to select the scope of the crawl or set a reasonable default. When crawling the tree, your app should follow the policies outlined in the Copying Person Records process.

Link Person Records

When you copy a Family Tree person record to your app tree or find a Family Tree person who matches a person in your app tree, store the Familysearch ID number or the resource URI with the associated record in your app. This is called “linking”.

Store a time stamp and Change History ETag of the FamilySearch person that you are linking to. This is referred to later in the Watch and Notify for Changes section of this document.

Match Person Records

In order to avoid adding duplicate records to Family Tree, you must be able to match person records in your app that have not yet been linked to existing persons in Family Tree. Matching can be done using the Person Matches API resource or the Person Search API resource.

When using the Person Matches resource, your app needs to be able to handle the following scenarios:

• One high confidence match found. When a single match is found, the user should be allowed to view more details and confirm the match. Your app should then create a link between the Family Tree person and the app tree person.
• Multiple high confidence matches found. When multiple matches are found, the user should have the option to link to one, and to begin the Resolve Duplicates process.
• No high confidence matches found. When no high confidence matches are found, your app may prompt the user to create a new person in Family Tree and create a link to that person. See the Add or Edit People process.
• Matching Persons Batch Process (to be determined). Your app has the option to perform match operations in a batch on behalf of the user. If high confidence matches are returned, your app can automatically link the match to the person in your app. For example, if a child record has been linked with Family Tree and the parents match exactly, the app may elect to link the child records as well and notify the user of the action taken.

Resolve Duplicates (Merge)

If multiple high confidence matches are found using the Person Matches API resource, your app can offer the user the opportunity to resolve duplicates.

Depending on the results, your app needs to handle the following scenarios:

• Not a Match. If a user decides that a match result is not a match, allow the user to mark that result as “Not a Match” and POST this information using the Person Not a Match List API resource. This prevents the match result from being reported as a match in future queries.
• Multiple Matches. If the user determines that multiple records match, then your app can allow the user to merge the records into one, eliminating the duplication. To combine two records into one person record, see the Person Merge resource and the Merging guide. Make sure the user knows which information will survive, and allow the user the option to submit a reason for the merge.

Review Change History

The user should be able to access the change history associated with a person in Family Tree. Change information should include the type, the date, the user who made the change, the reason for the change, and the changed values.

Some changes can be restored. If a change can be restored, your app should allow users to restore the change. Changes that can be restored contain a link within their change entry with the rel of type “restore”. Your app should show the “restore” link only on those change history items that can be restored. See the Change History guide and the Restore Change API resource documentation.

Watch and Notify for Changes

Your app should periodically check for changes made to linked Family Tree person records and associated resources. Cached resources have an ETag returned in response headers that is updated each time the data associated with that record is added, modified, or deleted. Store the ETag information to compare with future reads rather than manually checking and comparing each data element for changes.

To check for changes, you can make a HEAD request to various resource URIs that are linked to persons, relationships, discussions, sources, and other data types. Your app can also use the person and relationship change history resources to check for changes.

There is no prescribed way to notify the user that a change has occurred on a particular person. Once users are notified of a change, they need a way to view the change or compare the person record in your app tree to the person in Family Tree.

• Allow users to designate persons they want to watch, and notify the users when changes occur.
• Respond to HTTP header ETag changes by checking to see if the prior recorded ETag for each value has changed. Notify the user of outdated possibilities and direct them to a comparison process to see the difference between the third-party app tree and Family Tree. Or poll to examine the different values before displaying the third-party app tree value.
• For apps that perform temple ordinance reservations, make sure users acknowledge the Temple Ordinance Policy.