View source for GEPS 001: Relationship type event link

This page is for a description of the design to create a relationship type - event type link for use in reports. 

{{man note|Note|That due to the complexity of human relationships, this can not grasp all possibilities, but it should be more flexible than the present system.}}

== Introduction ==
The basis for this GEPS is bug {{bug|1121}} and [http://sourceforge.net/mailarchive/message.php?msg_id=11667959 this mail discussion]. 

The problem is the following: a family has a relationship type, and a set of events. For reports one needs to know what to print. Examples: 
* A family with relationship Unmarried and a Marriage event ? 
* A family with relationship Married and a Marriage and Divorce event ?
* A family with relationship Unmarried and no events? 
* A family with relationship Civil Union, how to indicate begin and end of this union ?

== What does GEDCOM say ? ==
Before doing anything, let's investigate how the GEDCOM standard solves this. 


First, there is no relationship type in GEDCOM, so export and import of GEDCOM means you loose all your relationship type information. 


So how does one know if somebody is Married in church or legally? GEDCOM says (read [http://homepages.rootsweb.com/~pmcbride/gedcom/55gcch2.htm#FAM_RECORD 1] and [http://homepages.rootsweb.com/~pmcbride/gedcom/55gcappa.htm 2]): 

 n [ ENGA | MARR | MARB | MARC ] [Y|<NULL>]  {1:1}
    +1 <<EVENT_DETAIL>>  {0:1}

So Marriage has a special event tag, where custom events have: 

 n  EVEN          {1:1}
    +1 <<EVENT_DETAIL>>  {0:1}

The tag MARR has the definition: 
  MARR {MARRIAGE}: = A legal, common-law, or customary event of creating a family unit 
  of a man and a woman as husband and wife. 

So marriage is the process of making a husband and wife, which are legal terms. Nowadays, law provides in contracts which make people partners, not necessarily husband and wife.

Note that Divorce also has its own event tag:

 DIV {DIVORCE}: = An event of dissolving a marriage through civil action. 

In catholic church the above is also possible after a canon law process. GEDCOM provides for the ANNULMENT event in that case. Strictly speaking, Catholic church does not recognise a re-marriage, but does recognise divorce. It would be simpler to use a term with a DIVORCE.

Anyway, it becomes interesting in the EVENT_DETAIL section which has

 n  TYPE <EVENT_DESCRIPTOR>  {0:1}

of which the definition is:
:A descriptor that should be used whenever the  EVEN  tag is used to define the event being cited. For example, if the event was a purchase of a residence, the  EVEN  tag would be followed by a subordinate TYPE tag with the value "Purchased Residence." '''Using this descriptor with any of the other defined event tags basically classifies the basic definition of the associated tag but does not change its basic process.''' 
It becomes better, as some examples are given:
:The  MARR  tag could be subordinated with a  TYPE  tag and EVENT_DESCRIPTOR value of Common Law. Other possible descriptor values might include "Childbirth%unmarried," "Common Law," or "Tribal Custom," for example. The event descriptor should use the same word or phrase and in the same language, when possible, as was used by the recorder of the event. Systems that display data from the GEDCOM form should be able to display the descriptor value in their screen or printed output. 

So GEDCOM allows to store relationship types subordinate to the MARR tag, solving the problem of knowing if couple is married, living together, unmarried, in civil union, ....

=== What does GRAMPS make of this? ===
Clearly, in GRAMPS the relationship type is meant to indicate how a couple relates to each other in the absence of events. Due to its position, users of GRAMPS will however also set the relationship type when events are given, which might lead to conflict. 

Does the TYPE event exist in GRAMPS? It does for custom tags, where it is used for the event name:
 1 EVEN
 2 TYPE Residence
However, for Marriage event, it is not used! 
There is a Description field in GRAMPS, but that uses something else: it is a text description not exported to GRAMPS, that on import is automatically filled up (eg Marriage of Tarzan, Joe and Doe, Jane)

'''Update''': The above might be an error in the coding. TYPE is used for the description in some of the other events. I find this highly confusing. I would put description always in a note. Eg:
NOTE DESCRIPTION:text which GRAMPS can export and import. I need to talk to Don about this.

== Proposal ==
The general built in solution would be the following: 
=== 6 relationship types ===
GRAMPS is given 6 standard relationship types, as opposed to the present four:
#'''Married''' : any religeous union
#'''Civil Marriage''': a civil legal union with highest legal bonding between husband and wife
#'''Civil Union''': all other civil legal union
#'''Cohabitation''': people living together without religeous or legal union, but with an implied relationship of mutual love.
#'''Unmarried''': a family with no bond whatsoever (for bastard children, ...) or a family living together without a mutual love.
#'''Unknown''' : Unknown

This means two new custom types are added to help distinguish the meaning of unmarried, as well as the civil unions which are not civil marriage.

=== Relationship -- standard event coupling ===
Every relationship is coupled to a standard event indicating the start and the end of a relationship. 

Proposal:
{| {{prettytable}}
!Relationship
!Start event
!Stop event
!priority
|-
|Married
|Marriage
|Annulment, Divorce
|1
|-
|Civil Marriage
|Civil Marriage
|Divorce
|2
|-
|Civil Union
|Civil Union
|Divorce, Civil Union Annulment
|2
|-
|Cohabitation
|Cohabitation
|Divorce, Civil Union Annulment, Split
|3
|-
|Unmarried
|''NA''
|''NA''
|4
|-
|Unknown
|''NA''
|''NA''
|5
|}

In the above, 5 new standard events are introduced:
# Civil Marriage : Now Marriage is used for this. Civil Marriage is the legal binding corresponding to highest legal binding possible between a couple. 
# Civil Union : Now Marriage is used for this. Civil Union would be a legal binding between a couple, which does not give the maximum of legal binding possible. 
# Civil Union Annulment : Civil Unions are typically very easy to stop, no divorce filing is needed.
# Cohabitation: People of a family starting to live together, without legal framework
# Split : The end of an informal cohabitation

However, on export to GEDCOM, these relationships are exported as MARR and DIV events:
 Marriage       ==> MARR 
 Civil Marriage ==> MARR, TYPE = Civil Marriage
 Civil Union    ==> MARR, TYPE = Civil Union
 Cohabitation   ==> MARR, TYPE = Cohabitation
 Annulment      ==> ANUL
 Divorce        ==> DIVR
 Civil Union Annulment ==> DIVR, TYPE = Civil Union Annulment
 Split          ==> DIVR, TYPE = Cohabitation

Note that GEDCOM says to even use MARR, TYPE=Unmarried-Childbirth, but that looks overkill to me.


An event stopping a more involved relationship, automatically also stops one of the other relationships. That is, if there is a cohabitation event, then a marriage event, then a divorce event, then it follows automatically that also the cohabitation came to an end.<br \>
Note: One can argue that above is not always true. Here we follow the line that ''this'' family relationship came to an end, relationship type being married, although the family is now divorced. If the divorced couple keeps living together for convenience reasons, a new family should be created, with same parents, relationship type Unmarried, and event cohabitation.

=== Event description field for nuance ===
The event description field should be used for nuance. Eg. there are many legal bindings possible. 

Some examples. Jane and Joe are together. Following descriptions are possible in the event:
* Marriage of Jane and Joe - ''type Married''
* Chatholic Marriage of Jane and Joe - ''type Married''
* Hindu wedding of Jane and Joe - ''type Married''
* Civil Marriage of Jane and Joe - ''type Civil Marriage''
* Living Together contract of Jane and Joe - ''type Civil Union''
* Samboförhållande of Jane and Joe - ''type Civil Union'' 

=== Use of the connection === 
The reason for the above is to have better control of what reports print. I propose two possible schemes:
# Brief relationship summary
# Detailed relationship summary

In the brief form, the report looks at the relationship type, and prints extra information depending on the start and stop events of the relationship type

In the detailed form, the report tries to deduce from all events the history of relationship of a couple, ending with the relationship that is the relationship type of the family

== Alternate proposals ==

=== Event tagging ===

The idea of a relationship between events is more common than just union. For example, a trip could be seen as a series of events that are related (start, ports visited, return). Each stop could be seen as a date/place of the trip. Likewise, birth/baptism/death/burial could be a seen as a relation of a series of events.

An alternative proposal for handling these (and other, more general, uses) would be to put the event into a relationship with other events. One could put an event into a relationship by providing a unique name or names to the event. For example, if we allow a tagging section then the event can belong to zero or more groups by simply giving a tag name to the event.

One issue with this method would be ordering of the events inside a group. This could be handled by making all tags be a tuple of (tagname, index). Initially, the index can be set to zero (meaning un-ordered) or time (meaning in the order created), but if the user sorts the group, then the index can be changed to reflect the ordering.

== Use cases == 

Some use cases

=== 1. Example one===
Jane and Joe family has following data:
*Living together: 2000: event cohabitation
*child 1 : 2001
*Split : 2002: event Split
*Living together: 2003: event cohabitation
*child 2 : 2003
*Civil Union: 2006 (may): event civil marriage
*Marriage with a service ('rented priest'): 2006 (june) : event marriage,
*description: religious garden ceremony of Jane and Joe

The present relationship type would be married.
In reports the brief form would be: "He married Jane on june 2006"

In detailed report, the events are used to determine relationship type
"He lived together with Jane from 2000 untill 2002. He lives together
with Jane since 2003. He did a civil union with Jane on may 2006. He married Jane
on June 2006"

== Tools, further possibilities ==
With the above, the following is possible: 
=== Color code events ===
Relationship events can have a color in the event tab. Eg Green for start of relation, red for stop.

=== Check relationship type tool === 
A tool to check if the set relationship type corresponds to what GRAMPS deduces from the given events.

=== Custom relationship type tool ===
A tool so that people can attach to their custom relationship types also a start and stop event. 

'''Question:''' I only see use in this if somebody could give an example that indicates custom relationship types are actually useful. 

Examples:
* Relationship: Arranged Marriage: Not a good idea. Better to use relationship Marriage. The fact that it is arranged is an attribute/property.

== Code implementation ==

To be decided. 

=== Relationship - event coupling ===
Suggestion: I would not store the relationship-event binding in the database, but instead store it in the code. If custom types must be supported, a database solution would be needed, but I do not see the use at the moment

=== Brief and detailed summary ===
New functions in ReportUtils.

=== Localization === 
Expressing relationships is very different from country to country. Needs to be investigated. 
Eg, civil union cannot be 'He civil union Jane on 12 august', but 'He married Jane on 12 august is ok'. 'He entered into a civil union with Jane on 13 August' is also OK.

=== Grammatical tenses ===

''CIVIL UNION'', ''UNMARRIED'' or ''CUSTOM'' relationship types (others than ''MARRIED'') do not make a difference between present tense and past tense.
Need to add new groups/dicts with "has a relationship with" if person is still alive :
 {
 Person.UNKNOWN : _('This person has a relationship with %(spouse)s.'), 
 Person.MALE : _('He has a relationship with %(spouse)s.'), 
 Person.FEMALE : _('She has a relationship with %(spouse)s.'),
 'succinct' : _('Relationship with %(spouse)s.'),
 }

see bug# {{bug|3386}}.

=== Source support?===

Should Gramps allow source on types of relation?

== How about occupation, ... ==
MARR is not the only custom event tag in GEDCOM. However, the discussion here is limited to relationships, so MARR and DIVR.

[[Category:GEPS|R]]