diff --git a/specifications/conceptual-model-specification.md b/specifications/conceptual-model-specification.md index da7eb12e..873c967c 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,36 @@ 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 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 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. + + ## 2.2 The "Relationship" Data Type @@ -290,7 +320,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 +329,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`. @@ -436,16 +475,27 @@ 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. | 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 @@ -475,34 +525,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. diff --git a/specifications/json-format-specification.md b/specifications/json-format-specification.md index 7f45dc12..ac08f430 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/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 diff --git a/specifications/xml-format-specification.md b/specifications/xml-format-specification.md index eac1c9e0..622968c3 100644 --- a/specifications/xml-format-specification.md +++ b/specifications/xml-format-specification.md @@ -467,7 +467,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)