From ec8946925e7346c9ecafe9227d1fc3bbf8419be8 Mon Sep 17 00:00:00 2001 From: Ryan Heaton Date: Thu, 14 Mar 2013 16:20:53 -0600 Subject: [PATCH 1/7] removing the 'about' property of 'PlaceDescription' and specifying more meaning of the 'identifiers' property --- specifications/conceptual-model-specification.md | 7 +++---- specifications/json-format-specification.md | 1 - specifications/xml-format-specification.md | 1 - 3 files changed, 3 insertions(+), 6 deletions(-) diff --git a/specifications/conceptual-model-specification.md b/specifications/conceptual-model-specification.md index 32ca4b81..c8cb9efb 100644 --- a/specifications/conceptual-model-specification.md +++ b/specifications/conceptual-model-specification.md @@ -416,14 +416,13 @@ This data type extends the following data type: name | description | data type | constraints ------|-------------|-----------|------------ -about | A uniform resource identifier (URI) for the place being described. This can be used for associating descriptions of the same place. | [URI](#uri) | OPTIONAL. names | A list of standardized (or normalized), fully-qualified (in terms of what is known of the applicable jurisdictional hierarchy) names for this place that are applicable to this description of this place. | List of [http://gedcomx.org/v1/TextValue](#text-value). Order is preserved. | REQUIRED. The list MUST contain at least one name. type | An implementation-specific uniform resource identifier (URI) used to identify the type of a place (e.g., address, city, county, province, state, country, etc.). | [URI](#uri) | OPTIONAL. There is no current plan to define a type vocabulary for place descriptions in GEDCOM X. temporalDescription | A description of the time period to which this place description is relevant. | [`http://gedcomx.org/v1/Date`](#conclusion-date) | OPTIONAL. -latitude | Degrees north or south of the Equator (0.0 degrees). | IEEE 754 binary64 value | OPTIONAL. If provided, MUST provide `longitude` also. Values range from −90.0 degrees (south) to 90.0 degrees (north). It is assumed that all instances of `PlaceDescription` that share identical `about` values will also have identical `latitude` values. -longitude | Angular distance in degrees, relative to the Prime Meridian. | IEEE 754 binary64 value | OPTIONAL. If provided, MUST provide `latitude` also. Values range from −180.0 degrees (west of the Meridian) to 180.0 degrees (east of the Meridian). It is assumed that all instances of `PlaceDescription` that share identical `about` values will also have identical `longitude` values. +latitude | Degrees north or south of the Equator (0.0 degrees). | IEEE 754 binary64 value | OPTIONAL. If provided, MUST provide `longitude` also. Values range from −90.0 degrees (south) to 90.0 degrees (north). It is assumed that all instances of `PlaceDescription` that share an identical `Primary` identifier will also have identical `latitude` values. +longitude | Angular distance in degrees, relative to the Prime Meridian. | IEEE 754 binary64 value | OPTIONAL. If provided, MUST provide `latitude` also. Values range from −180.0 degrees (west of the Meridian) to 180.0 degrees (east of the Meridian). It is assumed that all instances of `PlaceDescription` that share an identical `Primary` identifier will also have identical `longitude` values. spatialDescription | A reference to a geospatial description of this place. | [`URI`](#uri) | OPTIONAL. It is RECOMMENDED that this geospatial description resolve to a KML document. -identifiers | A list of known identifiers for this place description (e.g., place authority identifiers). | List of [`http://gedcomx.org/v1/Identifier`](#identifier-type). Order is preserved. | OPTIONAL. +identifiers | A list of known identifiers for this place description (e.g., place authority identifiers). Multiple descriptions of the same place MAY be correlated via the `http://gedcomx.org/Primary` identifier. | List of [`http://gedcomx.org/v1/Identifier`](#identifier-type). Order is preserved. | OPTIONAL. attribution | Attribution metadata for this place description. | [`http://gedcomx.org/Attribution`](#attribution) | OPTIONAL. If not provided, the attribution of the containing data set (e.g. file) of the place description is assumed. diff --git a/specifications/json-format-specification.md b/specifications/json-format-specification.md index 11fc978d..29194b11 100644 --- a/specifications/json-format-specification.md +++ b/specifications/json-format-specification.md @@ -472,7 +472,6 @@ is defined as follows: name | description | JSON member | JSON object type -----|-------------|--------------|--------- -about | A uniform resource identifier (URI) for the place being described. | about | [`URI`](#uri) names | A list of standardized (or normalized), fully-qualified (in terms of what is known of the applicable jurisdictional hierarchy) names for this place that are applicable to this description of this place. | names | array of [`TextValue`](#text-value) type | A uniform resource identifier (URI) identifying the type of the place as it is applicable to this description. | type | [`URI`](#uri) temporalDescription | A description of the time period to which this place description is relevant. | temporalDescription | [`Date`](#conclusion-date) diff --git a/specifications/xml-format-specification.md b/specifications/xml-format-specification.md index 6f183afa..7c02743a 100644 --- a/specifications/xml-format-specification.md +++ b/specifications/xml-format-specification.md @@ -469,7 +469,6 @@ The `gx:PlaceDescription` is used to (de)serialize the `http://gedcomx.org/v1/Pl name | description | XML property | XML type -----|-------------|--------------|--------- -about | A uniform resource identifier (URI) for the place being described. | about (attribute) | [anyURI](#uri) names | A list of standardized (or normalized), fully-qualified (in terms of what is known of the applicable jurisdictional hierarchy) names for this place that are applicable to this description of this place. | gx:name | [`gx:TextValue`](#text-value) type | A uniform resource identifier (URI) identifying the type of the place as it is applicable to this description. | type (attribute) | [`URI`](#uri) temporalDescription | A description of the time period to which this place description is relevant. | gx:temporalDescription | [`gx:Date`](#conclusion-date) From b9ee19442645c1a9ad50061680f4d5e765c517af Mon Sep 17 00:00:00 2001 From: Ryan Heaton Date: Tue, 19 Mar 2013 13:22:16 -0600 Subject: [PATCH 2/7] adjusting the 'known identifier type' lists to be specific to each data type --- .../conceptual-model-specification.md | 84 ++++++++++++------- 1 file changed, 53 insertions(+), 31 deletions(-) diff --git a/specifications/conceptual-model-specification.md b/specifications/conceptual-model-specification.md index e090a2d5..97a85148 100644 --- a/specifications/conceptual-model-specification.md +++ b/specifications/conceptual-model-specification.md @@ -172,7 +172,7 @@ This data type extends the following data type: name | description | data type | constraints ------|-------------|-----------|------------ -identifiers | Identifiers for the person. | List of [`http://gedcomx.org/v1/Identifier`](#identifier-type). Order is preserved. | OPTIONAL. +identifiers | Identifiers for the person. | List of [`http://gedcomx.org/v1/Identifier`](#identifier-type). Order is preserved. | OPTIONAL. If provided, use of a [known person identifier type](#known-person-identifier-types) is RECOMMENDED. persona | Whether this description of the person is to be constrained as a persona. | boolean | OPTIONAL. Default: `false`. Refer to [Persona Constraints](#persona-constraints). living | Whether the person is considered living. | boolean | OPTIONAL. gender | The conclusion about the gender of the person. | [`http://gedcomx.org/v1/Gender`](#gender) | OPTIONAL. @@ -201,6 +201,34 @@ Person data that is identified as a persona MUST conform to the following constr * All source references used by the persona MUST resolve to the same source description, although each reference MAY contain distinct qualifying information such as attribution. + + +### known person identifier types + +The following identifier types are defined by GEDCOM X as applicable to the `Person` data type. + +URI | description +----|------------ +`http://gedcomx.org/Primary` | The primary identifier for the person. A person SHOULD NOT have more than one `Primary` identifier. +`http://gedcomx.org/Evidence` | An identifier for the evidence that supports the person. For example, when a persona is extracted from a source, it MAY provide a unique identifier. As evidence for a person is gathered, the (working) person conclusion identifies the evidence used to support the conclusion by including each persona identifier in the list of identifiers for the person. +`http://gedcomx.org/Deprecated` | An identifier that has been relegated, deprecated, or otherwise downgraded. This identifier is commonly used as the result of a merge when what was once a primary identifier for a person is no longer primary. +`http://gedcomx.org/Persistent` | An identifier that is considered to be a long-term persistent identifier. Applications that provide persistent identifiers are claiming that links to the person using the identifier won't break. + +#### identifier type examples + +* Person "12345" merges into Person "67890". Person "67890" assumes identifier "12345". Identifier "12345" is of type `http://gedcomx.org/Deprecated` + because the merged person "12345" now uses identifier "67890". +* An online web application issues a persistent identifier of value `https://familysearch.org/pal:/12345` to a `Person` and the same identifier + is used as the primary identifier for the `Person`. The list of identifiers for the `Person` contains two identifiers with value `https://familysearch.org/pal:/12345`, + one of type `http://gedcomx.org/Primary` and one of type `http://gedcomx.org/Persistent`. +* An application allows a researcher to extract information from a single census record about a person. The application assigns an identifier "abcde" to the + `persona` extracted from the census record. The researcher extracts additional information about the person from a birth certificate and the application + assigns identifier "fghij" to the `persona` extracted from the birth certificate. As the researcher gathers and analyzes the evidence for the person, the + application creates a (working) `Person` conclusion that references the census record and the birth certificate as a source. When the researcher concludes + that person "abcde" and person "fghij" are the same person, the list of identifiers for the working `Person` includes two identifiers of type + `http://gedcomx.org/Evidence`: "abcde" and "fghij". + + ## 2.2 The "Relationship" Data Type @@ -290,7 +318,7 @@ The identifier for the `Agent` data type is: name | description | data type | constraints ------|-------------|-----------|------------ id | An identifier for the data structure holding the agent data. The id is to be used as a "fragment identifier" as defined by [RFC 3986, Section 3.5](http://tools.ietf.org/html/rfc3986#section-3.5). As such, the constraints of the id are provided in the definition of the media type (e.g. XML, JSON) of the data structure. | string | OPTIONAL. -identifiers | Identifiers for the agent. When an identifier for an agent is also an identifier for a person, the data in the person describes the agent. | List of [`http://gedcomx.org/v1/Identifier`](#identifier-type). Order is preserved. | OPTIONAL. +identifiers | Identifiers for the agent. | List of [`http://gedcomx.org/v1/Identifier`](#identifier-type). Order is preserved. | OPTIONAL. If provided, use of a [known agent identifier type](#known-agent-identifier-types) is RECOMMENDED. names | The names of the person or organization. If more than one name is provided, names are assumed to be given in order of preference, with the most preferred name in the first position in the list. | List of [`http://gedcomx.org/TextValue`](#text-value) | OPTIONAL. homepage | The homepage of the person or organization. | [URI](#uri) | OPTIONAL. openid | The [openid](http://openid.net/) of the person or organization. | [URI](#uri) | OPTIONAL. @@ -299,6 +327,15 @@ emails | The email addresses of the person or organization. | List of [URI](#ur phones | The phones (voice, fax, mobile) of the person or organization. | List of [URI](#uri) - MUST resolve to a valid phone number (e.g. "tel:+1-201-555-0123"). Order is preserved. | OPTIONAL. addresses | The addresses of the person or organization. | List of [`http://gedcomx.org/v1/Address`](#address). Order is preserved. | OPTIONAL. + + +### known agent identifier types + +The following identifier types are defined by GEDCOM X as applicable to the `Agent` data type. + +URI | description +----|------------ +`http://gedcomx.org/Person` | The agent's person identifier. Used to associate an `Agent` with a `Person`. @@ -442,9 +479,21 @@ temporalDescription | A description of the time period to which this place descr latitude | Degrees north or south of the Equator (0.0 degrees). | IEEE 754 binary64 value | OPTIONAL. If provided, MUST provide `longitude` also. Values range from −90.0 degrees (south) to 90.0 degrees (north). It is assumed that all instances of `PlaceDescription` that share an identical `Primary` identifier will also have identical `latitude` values. longitude | Angular distance in degrees, relative to the Prime Meridian. | IEEE 754 binary64 value | OPTIONAL. If provided, MUST provide `latitude` also. Values range from −180.0 degrees (west of the Meridian) to 180.0 degrees (east of the Meridian). It is assumed that all instances of `PlaceDescription` that share an identical `Primary` identifier will also have identical `longitude` values. spatialDescription | A reference to a geospatial description of this place. | [`URI`](#uri) | OPTIONAL. It is RECOMMENDED that this geospatial description resolve to a KML document. -identifiers | A list of known identifiers for this place description (e.g., place authority identifiers). Multiple descriptions of the same place MAY be correlated via the `http://gedcomx.org/Primary` identifier. | List of [`http://gedcomx.org/v1/Identifier`](#identifier-type). Order is preserved. | OPTIONAL. +identifiers | A list of known identifiers for this place description. | List of [`http://gedcomx.org/v1/Identifier`](#identifier-type). Order is preserved. | OPTIONAL. If provided, use of a [known place identifier type](#known-place-identifier-types) is RECOMMENDED. attribution | Attribution metadata for this place description. | [`http://gedcomx.org/Attribution`](#attribution) | OPTIONAL. If not provided, the attribution of the containing data set (e.g. file) of the place description is assumed. + + +### known place identifier types + +The following identifier types are defined by GEDCOM X as applicable to the `PlaceDescription` data type. + +URI | description +----|------------ +`http://gedcomx.org/Primary` | The primary identifier for the place. A place SHOULD NOT have more than one `Primary` identifier. Place descriptions that share the same `Primary` identifier are considered alternate descriptions of the same place. +`http://gedcomx.org/Authority` | An identifier for the place as provided by a separate authority, such as an authorities database. + + # 3. Component-Level Data Types @@ -474,34 +523,7 @@ The identifier for the "Identifier" data type is: name | description | data type | constraints ------|-------------|-----------|------------ value | The value of the identifier. | [URI](#uri) | REQUIRED. -type | URI identifying the type of the identifier. | [URI](#uri) | OPTIONAL. If provided, MUST resolve to an identifier type, and use of a [known identifier type](#known-identifier-types) is RECOMMENDED. - - - -### known identifier types - -The following identifier types are defined by GEDCOM X. - -URI | description -----|------------ -`http://gedcomx.org/Primary` | The primary identifier for the resource. -`http://gedcomx.org/Evidence` | An identifier for the evidence that supports the resource. For example, when a persona is extracted from a source, it MAY provide a unique identifier. As evidence for a person is gathered, the (working) person conclusion identifies the evidence used to support the conclusion by including each persona identifier in the list of identifiers for the person. -`http://gedcomx.org/Deprecated` | An identifier that has been relegated, deprecated, or otherwise downgraded. This identifier is commonly used as the result of a merge when what was once a primary identifier for a person is no longer primary. -`http://gedcomx.org/Persistent` | An identifier that is considered to be a long-term persistent identifier. Applications that provide persistent identifiers are claiming that links to the resource using the identifier won't break. - -### examples - -* Person "12345" merges into Person "67890". Person "67890" assumes identifier "12345". Identifier "12345" is of type `http://gedcomx.org/Deprecated` - because the merged person "12345" now uses identifier "67890". -* An online web application issues a persistent identifier of value `https://familysearch.org/pal:/12345` to a `Person` and the same identifier - is used as the primary identifier for the `Person`. The list of identifiers for the `Person` contains two identifiers with value `https://familysearch.org/pal:/12345`, - one of type `http://gedcomx.org/Primary` and one of type `http://gedcomx.org/Persistent`. -* An application allows a researcher to extract information from a single census record about a person. The application assigns an identifier "abcde" to the - `persona` extracted from the census record. The researcher extracts additional information about the person from a birth certificate and the application - assigns identifier "fghij" to the `persona` extracted from the birth certificate. As the researcher gathers and analyzes the evidence for the person, the - application creates a (working) `Person` conclusion that references the census record and the birth certificate as a source. When the researcher concludes - that person "abcde" and person "fghij" are the same person, the list of identifiers for the working `Person` includes two identifiers of type - `http://gedcomx.org/Evidence`: "abcde" and "fghij". +type | URI identifying the type of the identifier. | [URI](#uri) | REQUIRED. MUST resolve to an identifier type, and use of a known identifier type is RECOMMENDED. From 0161dd898a075feabb997a72b9ba4529159145d1 Mon Sep 17 00:00:00 2001 From: Ryan Heaton Date: Tue, 19 Mar 2013 15:09:09 -0600 Subject: [PATCH 3/7] initial draft of the n-tiered evidence architecture support --- .../conceptual-model-specification.md | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/specifications/conceptual-model-specification.md b/specifications/conceptual-model-specification.md index 97a85148..a1a427fb 100644 --- a/specifications/conceptual-model-specification.md +++ b/specifications/conceptual-model-specification.md @@ -201,6 +201,34 @@ Person data that is identified as a persona MUST conform to the following constr * All source references used by the persona MUST resolve to the same source description, although each reference MAY contain distinct qualifying information such as attribution. + + +### N-Tier Evidence Architecture + +GEDCOM X defines a concept called the "N-Tier Evidence Architecture" that is used to refer to a set of principles that +an application MAY choose to implement in support of the genealogical research process. When a researcher decides that +two or more personas describe the same person, an application that implements the N-Tier Evidence Architecture creates a +new instance of `Person` that "joins" the personas. A person that is used to "join" personas and/or other persons +is referred to as an "upper-tier person". + +The N-Tier Evidence Architecture stipulates the following: + +* Personas MUST be maintained under the [Persona Constraints](#persona-constraints). +* Upper-tier persons SHOULD NOT include the data of any of its associated personas except as to be used to resolve conflicts. +* Upper-tier persons SHOULD NOT provide source references. +* Upper-tier persons MAY join personas to personas, upper-tier persons to upper-tier persons, or upper-tier persons to personas. +* When providing a consolidated view of the evidence gathered for a specific person, an application does so by assembling the data + of each persona and using the data of each upper-tier person to resolve conflicts. The definition of the algorithms used to iterate + over each person, gather the data, and resolve conflicts are outside the scope of this specification. Such algorithms will be + subject to the constraints of the system and MAY include consideration of confidence levels and evidence type + (e.g. direct, indirect, negative, etc.). + +GEDCOM X defines the identifier type `http://gedcomx.org/ComponentEvidence` that is used to model upper-tier persons in +an N-Tier Evidence Architecture. Each upper-tier person refers to its components by providing an identifier of type +`http://gedcomx.org/ComponentEvidence` that resolves to each persona or upper-tier person being joined. Personas MUST be +identified by a value of `true` assigned to the `persona` property. + + ### known person identifier types @@ -213,6 +241,7 @@ URI | description `http://gedcomx.org/Evidence` | An identifier for the evidence that supports the person. For example, when a persona is extracted from a source, it MAY provide a unique identifier. As evidence for a person is gathered, the (working) person conclusion identifies the evidence used to support the conclusion by including each persona identifier in the list of identifiers for the person. `http://gedcomx.org/Deprecated` | An identifier that has been relegated, deprecated, or otherwise downgraded. This identifier is commonly used as the result of a merge when what was once a primary identifier for a person is no longer primary. `http://gedcomx.org/Persistent` | An identifier that is considered to be a long-term persistent identifier. Applications that provide persistent identifiers are claiming that links to the person using the identifier won't break. +`http://gedcomx.org/ComponentEvidence` | An identifier for the evidence that supports the person and MUST be considered a "component" of the person, as defined by an [N-Tier Evidence Architecture](#n-tier-architecture). #### identifier type examples From f5f1ce3f41f7a018bee896c8a887eb2df1b6837d Mon Sep 17 00:00:00 2001 From: Ryan Heaton Date: Tue, 19 Mar 2013 15:52:31 -0600 Subject: [PATCH 4/7] smoothing out the rough edges on some wording --- specifications/conceptual-model-specification.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specifications/conceptual-model-specification.md b/specifications/conceptual-model-specification.md index a1a427fb..cd516eca 100644 --- a/specifications/conceptual-model-specification.md +++ b/specifications/conceptual-model-specification.md @@ -214,7 +214,7 @@ is referred to as an "upper-tier person". The N-Tier Evidence Architecture stipulates the following: * Personas MUST be maintained under the [Persona Constraints](#persona-constraints). -* Upper-tier persons SHOULD NOT include the data of any of its associated personas except as to be used to resolve conflicts. +* Upper-tier persons SHOULD NOT repeat the data of any of its associated personas unless necessary to resolve conflicts. * Upper-tier persons SHOULD NOT provide source references. * Upper-tier persons MAY join personas to personas, upper-tier persons to upper-tier persons, or upper-tier persons to personas. * When providing a consolidated view of the evidence gathered for a specific person, an application does so by assembling the data @@ -226,7 +226,7 @@ The N-Tier Evidence Architecture stipulates the following: GEDCOM X defines the identifier type `http://gedcomx.org/ComponentEvidence` that is used to model upper-tier persons in an N-Tier Evidence Architecture. Each upper-tier person refers to its components by providing an identifier of type `http://gedcomx.org/ComponentEvidence` that resolves to each persona or upper-tier person being joined. Personas MUST be -identified by a value of `true` assigned to the `persona` property. +identified by setting the `persona` property to `true`. From 9b8f2baccc13e4a9b5b0e2b07a19c3835511a37b Mon Sep 17 00:00:00 2001 From: Ryan Heaton Date: Tue, 26 Mar 2013 13:43:17 -0600 Subject: [PATCH 5/7] adjustments to the vocabulary items in the definition of n-tier evidence architecture --- .../conceptual-model-specification.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/specifications/conceptual-model-specification.md b/specifications/conceptual-model-specification.md index cd516eca..4ccc26d6 100644 --- a/specifications/conceptual-model-specification.md +++ b/specifications/conceptual-model-specification.md @@ -209,23 +209,23 @@ GEDCOM X defines a concept called the "N-Tier Evidence Architecture" that is use an application MAY choose to implement in support of the genealogical research process. When a researcher decides that two or more personas describe the same person, an application that implements the N-Tier Evidence Architecture creates a new instance of `Person` that "joins" the personas. A person that is used to "join" personas and/or other persons -is referred to as an "upper-tier person". +is referred to as an "higher-tier person". The N-Tier Evidence Architecture stipulates the following: * Personas MUST be maintained under the [Persona Constraints](#persona-constraints). -* Upper-tier persons SHOULD NOT repeat the data of any of its associated personas unless necessary to resolve conflicts. -* Upper-tier persons SHOULD NOT provide source references. -* Upper-tier persons MAY join personas to personas, upper-tier persons to upper-tier persons, or upper-tier persons to personas. +* A higher-tier person SHOULD NOT repeat the data of its associated personas unless necessary to resolve conflicts. +* A higher-tier person SHOULD NOT have source references. +* A higher-tier person MAY join personas to personas, higher-tier persons to higher-tier persons, or higher-tier persons to personas. * When providing a consolidated view of the evidence gathered for a specific person, an application does so by assembling the data - of each persona and using the data of each upper-tier person to resolve conflicts. The definition of the algorithms used to iterate + of each persona and using the data of each higher-tier person to resolve conflicts. The definition of the algorithms used to iterate over each person, gather the data, and resolve conflicts are outside the scope of this specification. Such algorithms will be - subject to the constraints of the system and MAY include consideration of confidence levels and evidence type + subject to the constraints of the system and MAY include consideration of confidence levels, data types and evidence type (e.g. direct, indirect, negative, etc.). -GEDCOM X defines the identifier type `http://gedcomx.org/ComponentEvidence` that is used to model upper-tier persons in -an N-Tier Evidence Architecture. Each upper-tier person refers to its components by providing an identifier of type -`http://gedcomx.org/ComponentEvidence` that resolves to each persona or upper-tier person being joined. Personas MUST be +GEDCOM X defines the identifier type `http://gedcomx.org/ComponentEvidence` that is used to model higher-tier persons in +an N-Tier Evidence Architecture. Each higher-tier person refers to its components by providing an identifier of type +`http://gedcomx.org/ComponentEvidence` that resolves to each persona or higher-tier person being joined. Personas MUST be identified by setting the `persona` property to `true`. From 3a67f4f4643e3088fbba93d179347c8841027288 Mon Sep 17 00:00:00 2001 From: Ryan Heaton Date: Tue, 26 Mar 2013 14:08:50 -0600 Subject: [PATCH 6/7] fixing some icky wording, clarifying some examples, renaming 'upper-tier' to 'higher-tier' --- specifications/conceptual-model-specification.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/specifications/conceptual-model-specification.md b/specifications/conceptual-model-specification.md index 4ccc26d6..98dcc48f 100644 --- a/specifications/conceptual-model-specification.md +++ b/specifications/conceptual-model-specification.md @@ -251,11 +251,17 @@ URI | description is used as the primary identifier for the `Person`. The list of identifiers for the `Person` contains two identifiers with value `https://familysearch.org/pal:/12345`, one of type `http://gedcomx.org/Primary` and one of type `http://gedcomx.org/Persistent`. * An application allows a researcher to extract information from a single census record about a person. The application assigns an identifier "abcde" to the - `persona` extracted from the census record. The researcher extracts additional information about the person from a birth certificate and the application - assigns identifier "fghij" to the `persona` extracted from the birth certificate. As the researcher gathers and analyzes the evidence for the person, the - application creates a (working) `Person` conclusion that references the census record and the birth certificate as a source. When the researcher concludes - that person "abcde" and person "fghij" are the same person, the list of identifiers for the working `Person` includes two identifiers of type - `http://gedcomx.org/Evidence`: "abcde" and "fghij". + `persona` extracted from the census record. The researcher extracts additional information about a person from a birth certificate and the application + assigns identifier "fghij" to the `persona` extracted from the birth certificate. As the researcher gathers and analyzes evidence, she concludes that + `persona` "abcde" and `persona` "fghij" apply to the same person. + * An application that does NOT implement the N-Tier Evidence Architecture creates a (working) `Person` conclusion that references the census record and + the birth certificate as a source. The list of identifiers for the working `Person` includes two identifiers of type `http://gedcomx.org/Evidence`: + one that resolves to `persona` "abcde" and another that resolves to `persona` "fghij". The working `Person` includes the gender, names, and facts + that the researcher believes to be true and applicable to the person. + * An application that implements the N-Tier Evidence Architecture creates a higher-tier person conclusion that includes two identifiers of type + `http://gedcomx.org/ComponentEvidence`: one that resolves to `persona` "abcde" and another that resolves to `persona` "fghij". The higher-tier person + MUST NOT cite any sources, and it SHOULD NOT contain any names, facts, or a gender except as to be used to resolve any conflicts between `persona` + "abcde" and `persona` "fghij". From a113ea8541899c31a3768b37183b875c2c1b748f Mon Sep 17 00:00:00 2001 From: Ryan Heaton Date: Tue, 26 Mar 2013 14:39:36 -0600 Subject: [PATCH 7/7] extracting the n-tier architecture into a separate specification --- .../conceptual-model-specification.md | 41 +------ ...ier-evidence-architecture-specification.md | 107 ++++++++++++++++++ 2 files changed, 111 insertions(+), 37 deletions(-) create mode 100644 specifications/n-tier-evidence-architecture-specification.md diff --git a/specifications/conceptual-model-specification.md b/specifications/conceptual-model-specification.md index 98dcc48f..873c967c 100644 --- a/specifications/conceptual-model-specification.md +++ b/specifications/conceptual-model-specification.md @@ -201,33 +201,6 @@ Person data that is identified as a persona MUST conform to the following constr * All source references used by the persona MUST resolve to the same source description, although each reference MAY contain distinct qualifying information such as attribution. - - -### N-Tier Evidence Architecture - -GEDCOM X defines a concept called the "N-Tier Evidence Architecture" that is used to refer to a set of principles that -an application MAY choose to implement in support of the genealogical research process. When a researcher decides that -two or more personas describe the same person, an application that implements the N-Tier Evidence Architecture creates a -new instance of `Person` that "joins" the personas. A person that is used to "join" personas and/or other persons -is referred to as an "higher-tier person". - -The N-Tier Evidence Architecture stipulates the following: - -* Personas MUST be maintained under the [Persona Constraints](#persona-constraints). -* A higher-tier person SHOULD NOT repeat the data of its associated personas unless necessary to resolve conflicts. -* A higher-tier person SHOULD NOT have source references. -* A higher-tier person MAY join personas to personas, higher-tier persons to higher-tier persons, or higher-tier persons to personas. -* When providing a consolidated view of the evidence gathered for a specific person, an application does so by assembling the data - of each persona and using the data of each higher-tier person to resolve conflicts. The definition of the algorithms used to iterate - over each person, gather the data, and resolve conflicts are outside the scope of this specification. Such algorithms will be - subject to the constraints of the system and MAY include consideration of confidence levels, data types and evidence type - (e.g. direct, indirect, negative, etc.). - -GEDCOM X defines the identifier type `http://gedcomx.org/ComponentEvidence` that is used to model higher-tier persons in -an N-Tier Evidence Architecture. Each higher-tier person refers to its components by providing an identifier of type -`http://gedcomx.org/ComponentEvidence` that resolves to each persona or higher-tier person being joined. Personas MUST be -identified by setting the `persona` property to `true`. - @@ -241,7 +214,6 @@ URI | description `http://gedcomx.org/Evidence` | An identifier for the evidence that supports the person. For example, when a persona is extracted from a source, it MAY provide a unique identifier. As evidence for a person is gathered, the (working) person conclusion identifies the evidence used to support the conclusion by including each persona identifier in the list of identifiers for the person. `http://gedcomx.org/Deprecated` | An identifier that has been relegated, deprecated, or otherwise downgraded. This identifier is commonly used as the result of a merge when what was once a primary identifier for a person is no longer primary. `http://gedcomx.org/Persistent` | An identifier that is considered to be a long-term persistent identifier. Applications that provide persistent identifiers are claiming that links to the person using the identifier won't break. -`http://gedcomx.org/ComponentEvidence` | An identifier for the evidence that supports the person and MUST be considered a "component" of the person, as defined by an [N-Tier Evidence Architecture](#n-tier-architecture). #### identifier type examples @@ -253,15 +225,10 @@ URI | description * An application allows a researcher to extract information from a single census record about a person. The application assigns an identifier "abcde" to the `persona` extracted from the census record. The researcher extracts additional information about a person from a birth certificate and the application assigns identifier "fghij" to the `persona` extracted from the birth certificate. As the researcher gathers and analyzes evidence, she concludes that - `persona` "abcde" and `persona` "fghij" apply to the same person. - * An application that does NOT implement the N-Tier Evidence Architecture creates a (working) `Person` conclusion that references the census record and - the birth certificate as a source. The list of identifiers for the working `Person` includes two identifiers of type `http://gedcomx.org/Evidence`: - one that resolves to `persona` "abcde" and another that resolves to `persona` "fghij". The working `Person` includes the gender, names, and facts - that the researcher believes to be true and applicable to the person. - * An application that implements the N-Tier Evidence Architecture creates a higher-tier person conclusion that includes two identifiers of type - `http://gedcomx.org/ComponentEvidence`: one that resolves to `persona` "abcde" and another that resolves to `persona` "fghij". The higher-tier person - MUST NOT cite any sources, and it SHOULD NOT contain any names, facts, or a gender except as to be used to resolve any conflicts between `persona` - "abcde" and `persona` "fghij". + `persona` "abcde" and `persona` "fghij" apply to the same person. An application creates a (working) `Person` conclusion that references the census record and + the birth certificate as a source. The list of identifiers for the working `Person` includes two identifiers of type `http://gedcomx.org/Evidence`: + one that resolves to `persona` "abcde" and another that resolves to `persona` "fghij". The working `Person` includes the gender, names, and facts + that the researcher believes to be true and applicable to the person. diff --git a/specifications/n-tier-evidence-architecture-specification.md b/specifications/n-tier-evidence-architecture-specification.md new file mode 100644 index 00000000..37f9f7ac --- /dev/null +++ b/specifications/n-tier-evidence-architecture-specification.md @@ -0,0 +1,107 @@ +# The GEDCOM X N-Tier Evidence Architecture + +## Status + +This document defines a concept called the "N-Tier Evidence Architecture" which consists of a set of principles +and rules that may be implemented by a genealogical data provider in support of the genealogical research process, +and requests discussion and suggestions for improvements. + +The current state of this document is as a DRAFT, and as such, the document +may be subject to changes, including backwards-incompatible changes, according to the +discussion and suggestions for improvement. + +## Copyright Notice + +Copyright 2011-2012 Intellectual Reserve, Inc. + +## License + +This document is distributed under a Creative Commons Attribution-ShareAlike license. +For details, see: + +http://creativecommons.org/licenses/by-sa/3.0/ + +# 1. Introduction + +The N-Tier Evidence Architecture is a concept that consists of a set of principles +and rules that may be implemented by a genealogical data provider in support of the genealogical research process. + +## 1.1 Identifier, Version, and Dependencies + +The identifier for this specification is: + +`http://gedcomx.org/n-tier-evidence-architecture/v1` + +This specification depends on the conceptual model specification identified +by [`http://gedcomx.org/conceptual-model/v1`](https://github.com/FamilySearch/gedcomx/blob/master/specifications/conceptual-model-specification.md). + +## 1.2 Notational Conventions + +### 1.2.1 Keywords + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", +"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this +document are to be interpreted as described in BCP 14, +[RFC2119](http://tools.ietf.org/html/rfc2119), as scoped to those conformance +targets. + +### 1.2.2 Compliance + +An implementation of the N-Tier Evidence Architecture is "non-compliant" if it fails to satisfy +one or more of the MUST or REQUIRED level requirements. An implementation that satisfies all of +the MUST or REQUIRED and all of the SHOULD level requirements is said to be "unconditionally +compliant"; and implementation that satisfies all of the MUST level requirements but not all of the +SHOULD level requirements is said to be "conditionally compliant". + +### 1.2.3 Joining Personas + +When a researcher decides that two or more personas describe the same person, a new instance of `http://gedcomx.org/v1/Person` is created +that referenced each person by an identifier. The instance is said to "join" the personas. + +### 1.2.4 Higher-Tier Person + +An instance of the `http://gedcomx.org/v1/Person` data type that is used to join personas and/or other persons is referred to as +a "higher-tier person". + +## 1.3 Examples + +An application allows a researcher to extract information from a single census record about a person. The application assigns an identifier "abcde" to the +`persona` extracted from the census record. The researcher extracts additional information about a person from a birth certificate and the application +assigns identifier "fghij" to the `persona` extracted from the birth certificate. As the researcher gathers and analyzes evidence, she concludes that +`persona` "abcde" and `persona` "fghij" apply to the same person. + +An application that implements the N-Tier Evidence Architecture creates a higher-tier person conclusion that includes two identifiers of type +`http://gedcomx.org/ComponentEvidence`: one that resolves to `persona` "abcde" and another that resolves to `persona` "fghij". The higher-tier person +MUST NOT cite any sources, and it SHOULD NOT contain any names, facts, or a gender except as to be used to resolve any conflicts between `persona` +"abcde" and `persona` "fghij". + +# 2. Constraints + +An N-Tier Evidence Architecture conforms to the following constraints: + +* Personas MUST be maintained under the [Persona Constraints](https://github.com/FamilySearch/gedcomx/blob/master/specifications/conceptual-model-specification.md#persona-constraints) + as defined by the [GEDCOM X Conceptual Model](https://github.com/FamilySearch/gedcomx/blob/master/specifications/conceptual-model-specification.md). +* A higher-tier person SHOULD NOT repeat the data of its associated personas unless necessary to resolve conflicts. +* A higher-tier person MUST NOT have source references. +* A higher-tier person MAY join personas to personas, higher-tier persons to higher-tier persons, or higher-tier persons to personas. + +## 2.1 Presentation of Higher-Tier Persons + +When providing a consolidated view of the evidence gathered for a specific person, an application does so by assembling the data +of each persona and higher-tier that is joined by the higher-tier person. + +### 2.1.1 Resolving Conflicts Between Personas + +If there are conflicts between two personas that have been joined, the application uses data of each higher-tier person +to resolve them. + +todo: fill in the details about how to resolve conflicts, taking into account confidence levels, data types and evidence type (e.g. direct, indirect, negative, etc.). + +# 3. Data Types + +## 3.1 The "Component Evidence" Identifier Type + +The identifier type `http://gedcomx.org/ComponentEvidence` is used to model higher-tier persons in +an N-Tier Evidence Architecture. Each higher-tier person refers to its components by providing an identifier of type +`http://gedcomx.org/ComponentEvidence` that resolves to each persona or higher-tier person being joined. Personas MUST be +identified by setting the `persona` property to `true`. \ No newline at end of file