Family Echo FamilyScript

Family Echo - FamilyScript File Format


FamilyScript is the native file format of Family Echo. Each FamilyScript file describes the people in a single family. FamilyScript is optimized for efficient communication and fast interpretation by web browsers.

This page contains a technical description of the FamilyScript file format, to help developers write FamilyScript tools and importers. Regular users of Family Echo have no need to read this document.

Data model

Each person in a family is identified by a unique alphanumeric ID such as R3QK8. IDs are case sensitive and contain one or more characters from A-z, a-z or 0-9.

Each person can have associated facts, such as their birth place or email address. Each fact is identified by a single character tag. For example, v is the tag for birth place and e is the tag for email. Tags are case sensitive. A person may only have one fact of each type. All tags are optional for all people.

File structure

A FamilyScript file is split into lines. Lines may be separated by LF (ASCII 10), CR (ASCII 13) or CRLF newlines. All text is encoded as UTF-8 Unicode, which is backwards compatible with US-ASCII.

The meaning of a line is set by its first character. Currently, only lines which begin with the character i or p have meaning. All other lines should be treated as comments and silently ignored.

Lines beginning i

Lines that begin with i describe an individual person. The i character is followed by the unique ID of this person, whom we call the subject of the line. The rest of the line contains zero or more facts about this subject.

Each fact is preceded by a tab character (ASCII 9), then a single-character tag, then some text data. In this guide we'll represent tab characters as a  ¬  symbol. Remember that tag v means birth place and e means email. The example below sets the birth place of person ID R3QK8 to Chicago and her email address to

iR3QK8 ¬ vChicago ¬

Tags which are not recognized should be silently ignored. Within the data that follows a tag character, \ slashes should be written as \\, tabs as \t and newlines as \n.

Basic relationships

For each person in a FamilyScript, three relatives may be specified as properties of that person - their mother, father and current partner. Many other relationships in a family are calculated from this information. For example, two people are considered half-siblings if they have one, but not two, parents in common.

A subject's relatives are specified by the appropriate tag, followed by the unique ID of the relative. For example, f is the tag for father, so fDKP41 on a line means the subject's father is person ID DKP41.

Tags for i lines

Below is a full list of tags for i lines and the types of fact they represent. Remember that tags are case sensitive. Most facts are in free text form, while a few have specific representations that are described in more detail below.

Personal Information
Tag Fact Example or Notes
 p  First names Separated by spaces, e.g. Mary Alice
 l  Surname now Example: Smith
 q  Surname at birth Example: Jones
 g  Gender m for male, f for female, o for other
 b  Birth date YYYYMMDD - see note on dates.
 z  Deceased 1 to indicate that person has died.
 d  Death date YYYYMMDD - see note on dates.
 r  Photo imageid width height - see note on images.
Basic Relationships
Tag Fact Example or Notes
 m  Mother ID of mother, e.g. F4XB6
 f  Father ID of father, e.g. JD80F
 s  Current partner ID of current partner, e.g. PWAN7
Contact Information
Tag Fact Example or Notes
 e  Email Example:
 w  Website Example:
 B  Blog Example:
 P  Photo site Example:
 t  Home tel Example: 212 123 4567
 k  Work tel Example: 212 789 3456
 u  Mobile Example: 212 123 2468
 S  Skype Example: mary_alice_smith
 a  Address Example: 123 Mass Ave\nNew York 10024\nUSA
 C  Other contact Example: ICQ maryalice123
Biographical Information
Tag Fact Example or Notes
 v  Birth place Example: Chicago
 y  Death place Ignored if person has not died (see z)
 U  Burial place Ignored if person has not died (see z)
 F  Burial date YYYYMMDD - see note on dates.
 j  Profession Example: Administrator
 E  Company Example: Acme Corporation
 I  Interests Example: Movies, literature, history
 A  Activities Example: Travel, painting
 o  Bio notes Example: Also lived in Netherlands

Note on dates (tags b, d and F): Dates are specified in the Gregorian calendar in YYYYMMDD format. For example, July 14th 1968 is represented by 19680714. If only part of a date is known, the other parts can be padded with zeroes. For example, 19530000 means some time in 1953 and 00001106 means November 6th in an unknown year.

Note on images (tag r): Images are stored in separate files and referenced by an imageid. If the FamilyScript is on disk, a parser should search for a JPEG file titled image-imageid.jpg in the same directory as the FamilyScript file. After the imageid, the width and height of the source image file may optionally be specified in pixels, separated by spaces. It is recommended to include these dimensions to help web browsers display the image correctly.

Lines beginning p

Lines that begin with p provide information on the connection between a pair of people. The p character is followed by the unique ID of one person in the pair, then a space, then the unique ID of the second person in the pair. The rest of the line contains zero or more facts about this pair of people.

As with lines beginning i, each fact is preceded by a tab, then a single-character tag, then some data. For example, if the e tag is followed by a digit 1, this means that the individuals in the pair have been partners, either currently or in the past. The example below states that individuals R3QK8 and F4KDT have been partners:

pR3QK8 F4KDT ¬ e1

Tags for p lines

Below is a full list of tags for p lines and the types of fact they represent. Remember that tags are case sensitive.

Partnership Basics
Tag Fact Example or Notes
 e  (Ex-)partners 1 means the two people are currently partners, or have been in the past.
Not needed if we know about the partnership for other reasons - see final notes.
 g  Type of (ex-)partnership m for married, e for engaged, r for generic relationship, s for separated,
d for divorced, a for annulled.
Partnership Beginnings
Tag Fact Example or Notes
 b  Start date YYYYMMDD - start of generic relationship.
 r  Engagement date YYYYMMDD
 m  Wedding date YYYYMMDD - for all marriage-related partnerships, where g is m, s, d or a.
 w  Wedding location Example: Las Vegas
Partnership Endings
Tag Fact Example or Notes
 s  Separation date YYYYMMDD
 d  Divorce date YYYYMMDD
 a  Annulment date YYYYMMDD
 z  End date YYYYMMDD - generic end of relationship, where g is m, e or r.

Example FamilyScript

Tab characters are represented as a  ¬  symbol in the example:

iR3QK8 ¬ pMary Alice ¬ lSmith ¬ qJones ¬ gf ¬ b19680714 ¬ sMU2MO ¬ jDoctor
iMU2MO ¬ pJohn ¬ lSmith ¬ gm ¬ b19650327 ¬ sR3QK8 ¬ APainting
iR3QK8 ¬ fDKP41 ¬ a123 Mass Ave\nNew York 10024\nUSA ¬ t212 123 4567 ¬
iDKP41 ¬ pTodd ¬ lJones ¬ gm ¬ b19141000 ¬ z1 ¬ d20020805 ¬ r482934937 240 160 ¬ oDrinker
iF4KDT ¬ pPeter ¬ lBrown ¬ gm ¬ EAcme Corporation
pR3QK8 F4KDT ¬ e1 ¬ ga ¬ m19940214 ¬ wLas Vegas ¬ a19940217
pDKP41 R3QK8 ¬ ge ¬ r19971000

This FamilyScript describes four people:

  • Person ID R3QK8 - Mary Alice Smith (formerly Jones), a female born on July 14th 1968.
  • Person ID MU2MO - John Smith, a male born on March 3rd 1965.
  • Person ID DKP41 - Todd Jones, a male born in October 1914 who died on August 5th 2002.
  • Person ID F4KDT - Peter Brown, another male about whom we know little.
The following relationships are described by the FamilyScript:
  • Mary (R3QK8) and John (MU2MO) are current partners according to lines 1 and 2. The final p line indicates that they have been engaged since October 1997.
  • Todd (DKP41) is Mary's father according to line 3.
  • Peter (F4KDT) is an ex-partner of Mary. They married in Las Vegas on 14th February 1994, but annulled the marriage 3 days later.
Other information is as follows. Mary is a doctor, John does painting, Peter works for Acme Corporation, and there is a biographical note that Todd was a drinker. We also have some contact details for Mary - an address, home phone number and email. Finally, there is a JPEG image 482934937.jpg containing a photo of Todd sized 240x160 pixels.

Final Notes

  • White space is meaningful and never ignored, except for repeated newlines. For this reason you should avoid extensive editing of FamilyScript files by hand.
  • FamilyScript files should be read in strict sequential order, both top-to-bottom and left-to-right. If a tag appears more than once for a specific person, or a specific pair of people, the last instance only should be kept.
  • There is no semantic difference between a tag which is omitted, and a tag which is followed by an empty string. Following the sequential rule above, this means facts can be 'unset' by including their tag with no data.
  • A person is included in the family if and only if they appear as the subject of an i line, or as one of the two subjects of a p line. This has two implications. First, the existence of a person can be 'declared' by an i line with no tags. Second, if a person never appears as a line subject, but is referenced as a relative of someone else, the relationship should be discarded. This should only be done after the complete FamilyScript file has been read.
  • Same-sex marriage, partnership and co-parenthood are explicitly supported by FamilyScript. If a person's parents are of the same gender, they can be arbitrarily assigned to the mother and father. This means two people should be considered full siblings even if their parents match in reverse.
  • Two people are considered to have been partners if one of these three conditions is fulfilled:
      (a) They are both specified as the other's current partner via the s tag in i lines.
      (b) They are declared as having been partners (e1) in a line beginning p.
      (c) They have children in common.
    If condition (a) is fulfilled, they are considered current partners. Otherwise they are ex-partners.


FamilyScript is designed to be easily extendable while maintaining backwards compatibility. It will be enhanced over time to support new features in Family Echo. Please send any comments through the feedback form.

About     FAQs     API     Baby Names     Resources     Terms / Data Policies     Help Forum     Send Feedback
© Familiality 2017 - All rights reserved