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, five relatives may be specified as properties of that person - their mother, father, primary partner, secondary mother and secondary father. 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  Given names Separated by spaces, e.g. Mary Alice
 N  Nickname Example: Peanut
 T  Title Example: Dr
 J  Suffix Example: III
 l  Surname now Example: Smith
 q  Surname at birth Example: Jones
 g  Gender m for male, f for female, o for other + optional description e.g. oTrans
 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.
 O  Birth order See note on birth order.
Basic Relationships
Tag Fact Example or Notes
 m  Mother (primary) ID of mother, e.g. F4XB6
 f  Father (primary) ID of father, e.g. JD80F
 V  Primary parent type b for biological, a for adopted, f for foster, s for step
 s  Primary partner ID of primary partner, e.g. PWAN7
 X  Secondary mother ID of secondary mother, e.g. K1NY5
 Y  Secondary father ID of secondary father, e.g. JD80F
 W  Secondary parent type b for biological, a for adopted, f for foster, s for step
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
 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)
 Z  Cause of death 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. Dates before the Common Era (BC/BCE) have a prefix B. For example, B00270330 means March 30th in the year 27 BCE. Symbol suffixes can be used to represent non-exact dates, where ~ means approximate, > means before the given date and < means after the given date. For example, 20050400~ means approximately April 2005. Date ranges are represented with a hyphen, e.g. 20030428-20040115 means between 28th April 2003 and 15th January 2004.

Note on birth order (tag O): A birth order is specified as a number, which is compared to other siblings' birth order values and/or birth dates (where lower means older). For the purposes of ordering, the birth order value is ignored for people whose birth date (or even just birth year) is known. When comparing a birth order and a birth date, the birth date is first converted to an integer whose value is year*10000+month*100+day (where a BCE year is negative). Unlike birth dates, birth orders can contain decimal places. For example, someone with birth order 19530350.25 and no birth date is considered older than a sibling born on March 31st, 1953 and younger than one born on April 1st, 1953.

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 have been partners at some time.
2 means the two people are current partners.
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,
o for other + optional description e.g. oLife partnership
Partnership Beginnings
Tag Fact Example or Notes
 b  Start date YYYYMMDD - start of generic relationship (see above note on dates).
 r  Engagement date YYYYMMDD - see above note on dates.
 m  Marriage date YYYYMMDD - for all marriage-related partnerships, where g is m, s, d or a (see above note on dates).
 w  Marriage location Example: Las Vegas
Partnership Endings
Tag Fact Example or Notes
 s  Separation date YYYYMMDD - see above note on dates.
 d  Divorce date YYYYMMDD - see above note on dates.
 a  Annulment date YYYYMMDD - see above note on dates.
 z  End date YYYYMMDD - generic end of relationship, where g is m, e or r (see above note on dates).

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 as current partners if either: (a) they are both specified as the other's primary partner via the s tag in i lines, or (b) they are declared as current partners (e2) in a line beginning p.
  • Two people are considered as ex-partners if they are not current partners and either: (a) they have children in common, or (b) they are declared as ex-partners (e1) in a line beginning p.


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 2007-2023 - All rights reserved