|
Family Echo - FamilyScript File Format
Introduction
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 mary@smith.org:
iR3QK8 ¬ vChicago ¬ emary@smith.org
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.
Relationships
For each person in a FamilyScript, seven other people may be specified as properties of that person
- their mother, father, current partner, and two additional sets of mothers and/or fathers.
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. |
|
Relationships
|
| Tag |
Fact |
Example or Notes |
| m |
Mother (primary parent set) |
ID of mother, e.g. F4XB6 |
| f |
Father (primary parent set) |
ID of father, e.g. JD80F |
| V |
Primary parent set type |
b for biological, a for adopted, f for foster, s for step, g for god |
| s |
Current partner |
ID of current partner, e.g. PWAN7 |
| X |
Mother (second parent set) |
ID of mother in second parent set, e.g. K1NY5 |
| Y |
Father (second parent set) |
ID of father in second parent set, e.g. JD80F |
| W |
Second parent set type |
b for biological, a for adopted, f for foster, s for step, g for god |
| K |
Mother (third parent set) |
ID of mother in third parent set, e.g. S79ZW |
| L |
Father (third parent set) |
ID of father in third parent set, e.g. L4P3V |
| Q |
Third parent set type |
b for biological, a for adopted, f for foster, s for step, g for god |
|
Contact Information
|
| Tag |
Fact |
Example or Notes |
| e |
Email |
Example: mary@smith.org |
| w |
Website |
Example: http://www.mary.com/ |
| B |
Blog |
Example: http://mary.blogspot.com/ |
| P |
Photo site |
Example: http://www.mary.com/photos/ |
| 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 ¬ emary@smith.org
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.
Extensions
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.
|