GEDCOM X RS

Status

This document specifies a standard interface for a genealogical data application on the World Wide Web, 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

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

GEDCOM X RS is a specification that defines a standard interface for a genealogical data application on the World Wide Web. A set of data types are defined as extensions to the core GEDCOM X specification set and the GEDCOM X Record Extension to accommodate the requirements of a web-based application. The states of the application are identified and the transitions between the application states are defined.

A genealogical application that conforms to this specification uses the Hypertext Transfer Protocol (HTTP) to accept requests from and provide responses to client applications. This specification leverages the concepts and principles defined by HTTP to describe how a client can expect to interact with a conforming genealogical application.

1.1 Identifier, Version, and Dependencies

The identifier for this specification is:

http://gedcomx.org/rs/v1

For convenience, GEDCOM X RS may be referred to as "GEDCOM X RS 1.0". This specification uses "GEDCOM X RS" internally.

This specification references the GEDCOM X Conceptual Model specification identified by http://gedcomx.org/conceptual-model/v1.

This specification references the GEDCOM X XML specification identified by http://gedcomx.org/xml/v1.

This specification references the GEDCOM X JSON specification identified by http://gedcomx.org/json/v1.

This specification references the GEDCOM X Atom Extensions specification identified by http://gedcomx.org/atom-extensions/v1.

This specification references the GEDCOM X Record Extensions specification identified by http://gedcomx.org/records/v1.

This specification references the HTTP 1/1 specification, RFC 2616.

This specification uses RFC 5988, Web Linking to specify the means to declare state transitions.

This specification uses RFC 6570, URI Templates to specify the means to declare a range of URIs.

This specification references RFC 6749, OAuth 2.

This specification uses RFC 2388 to specify how to upload digital artifacts to a collection.

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, as scoped to those conformance targets.

1.2.2 Compliance

An implementation of GEDCOM X RS 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.3 Concepts and Definitions

1.3.1 Client

The "client" is software that reads, updates, or otherwise consumes the genealogical data application.

1.3.2 Server

The "server" is the software that provides the genealogical data application via HTTP.

1.3.3 Application States

GEDCOM X RS is defined by a set of application states. An "application state" is a snapshot of the state of genealogical data in an application at a specific point in time. Examples of an application state include resources such as persons, relationships, or sources.

1.3.4 State Transitions (i.e. "Links")

A client drives the state of a GEDCOM X application by capturing transitions from application state to application state. Each application state provides to the client the set of transitions (i.e. "links") to other application states that are available. For example, a client may be able to follow a link from a person to its source.

1.3.5 Operations

The set of available operations is constrained to the set defined by RFC 2616, Section 9.

1.3.6 Media Types

The data that is exchanged between a client and a server is encoded according to a specific "media type". Clients use content negotiation to determine which media type is used to represent data that is exchanged. For more information about media types, see Architecture of the World Wide Web, Volume One, Sections 3 and 4.

1.3.7 Application Entry Points

Each genealogical application has an "entry point" that takes the form of a URI that resolves to an application state. An application entry point is a well-known URI that is used to initiate interactions between a client and the server.

Each application determines its own entry points. It is RECOMMENDED that entry points include Collections, Collection, and Person.

1.4 Use of HTTP

Servers provide a GEDCOM X RS interface using RFC 2616, Hypertext Transfer Protocol. HTTP is used to exchange data and drive application state.

1.4.1 The Request

An HTTP request is issued by the client to initiate the exchange of application state. For more information about HTTP requests, see RFC 2616, Section 5.

1.4.2 The Response

An HTTP response is provided by the server in response to an HTTP request. For more information about HTTP responses, see RFC 2616, Section 6.

1.4.3 Content Negotiation

Content negotiation is the process by which a media type is selected to represent application state. For more information about content negotition, see RFC 2616, Section 12.

1.4.4 The OPTIONS Operation

The HTTP OPTIONS operation is a useful mechanisms for clients to determine the capabilities of the server for a given application state. A client can use the OPTIONS operation to determine (among other things) which HTTP methods are available.

example

request

OPTIONS /path/to/application/state

response

HTTP/1.1 204 No Content
Allow: OPTIONS,POST,GET,DELETE,HEAD

2. Data Type Extensions

This section defines a set of extensions to the GEDCOM X Conceptual Model and provides the representations of those data types in both XML and JSON as extensions to GEDCOM X JSON and GEDCOM X XML.

2.1 The "Link" Data Type

The Link data type defines a representation of an available transition from one application state to another. The base definition of a link is provided by RFC 5988.

Instances of Link can be reasonably expected as extension elements to any GEDCOM X data type, except data types that are defined by the GEDCOM X Conceptual Model to explicitly restrict extension properties.

identifier

The identifier for the Link data type is:

http://gedcomx.org/v1/Link

properties

name	description	data type	constraints
rel	Link relation identifier.	`URI`	REQUIRED.
href	Link target.	`URI`	OPTIONAL. If not provided, a `template` MUST be provided.
template	Link template, per RFC 6570.	URI Template	OPTIONAL. If not provided, a `href` MUST be provided.
type	Metadata about the available media type(s) of the resource being linked to.	string	OPTIONAL. The value of the "type" attribute is as defined by RFC 2616, Section 3.7.
accept	Metadata about the acceptable media type(s) that can be used to update (i.e. change the state of) the resource being linked to.	string	OPTIONAL. The value of the "accept" attribute is as defined by RFC 2616, Section 3.7.
allow	Metadata about the allowable methods that can be used to transition to the resource being linked.	string	OPTIONAL. The value of the "allow" attribute is as defined by RFC 2616, Section 14.7.
hreflang	The language of the resource being linked to.	string	OPTIONAL.
title	Human-readable information about the link.	string	OPTIONAL.

2.1.1 The "Link" XML Type and Element

The gx:Link XML type is used to (de)serialize the http://gedcomx.org/v1/Link data type. The gx:link XML element is used to provide instances of the gx:Link XML type as extension elements.

properties

name	description	XML property	XML type
rel	Link relation identifier.	rel (attribute)	anyURI
href	Link target.	href (attribute)	anyURI
template	Link template, per RFC 6570.	template (attribute)	xsd:string
type	Metadata about the available media type(s) of the resource being linked to.	type (attribute)	xsd:string
accept	Metadata about the acceptable media type(s) that can be used to update (i.e. change the state of) the resource being linked to.	accept (attribute)	xsd:string
allow	Metadata about the allowable methods that can be used to transition to the resource being linked.	allow (attribute)	xsd:string
hreflang	The language of the resource being linked to.	hreflang (attribute)	xsd:string
title	Human-readable information about the link.	title (attribute)	xsd:string

examples

<gx:link rel="..." href="..." template="..." type="..." accept="..." allow="..." hreflang="..." title="...">
  <!-- possibility of extension elements -->
</gx:link>

2.1.2 The "Link" JSON Type

The Link JSON type is used to (de)serialize the http://gedcomx.org/v1/Link data type.

properties

name	description	JSON member	JSON object type
rel	Link relation identifier.	rel	anyURI
href	Link target.	href	anyURI
template	Link template, per RFC 6570.	template	xsd:string
type	Metadata about the available media type(s) of the resource being linked to.	type	xsd:string
accept	Metadata about the acceptable media type(s) that can be used to update (i.e. change the state of) the resource being linked to.	accept	xsd:string
allow	Metadata about the allowable methods that can be used to transition to the resource being linked.	allow	xsd:string
hreflang	The language of the resource being linked to.	hreflang	xsd:string
title	Human-readable information about the link.	title	xsd:string

examples

{
  "rel" : "...",
  "href" : "...",
  "template" : "...",
  "type" : "...",
  "accept" : "...",
  "allow" : "...",
  "hreflang" : "...",

  ...possibility of extension elements...
}

2.1.3 The "Links" JSON Type and Member

For convenience in working with JSON, a list of instances of the http://gedcomx.org/v1/Link data type are provided as a JSON object, with the members of the object being the value of the rel property of the link. The links member is reserved to be used as an instance of this "Links" JSON Type.

examples

The following example shows how a list of links is serialized in JSON.

"links" {
  "rel1" : {
    "href" : "...",
  },
  "rel2" : {
    "href" : "...",
  },
  ...etc...
}

2.2 The "DisplayProperties" Data Type

The DisplayProperties data type defines a set of properties for convenience in displaying a summary of a person to a user. All display property values are provided as appropriate for the locale requested by the consuming application, or the default locale if no locale was specified. Instances of DisplayProperties can be expected as extension elements to the Person Data Type.

identifier

The identifier for the DisplayProperties data type is:

http://gedcomx.org/v1/DisplayProperties

properties

name	description	data type	constraints
name	The name of the person.	string	OPTIONAL
gender	The displayable label for the gender of the person.	string	OPTIONAL
lifespan	The displayable label for the lifespan of the person.	string	OPTIONAL
birthDate	The displayable label for the birth date of the person.	string	OPTIONAL
birthPlace	The displayable label for the birth place of the person.	string	OPTIONAL
deathDate	The displayable label for the death date of the person.	string	OPTIONAL
deathPlace	The displayable label for the death place of the person.	string	OPTIONAL
marriageDate	The displayable label for the marriage date of the person.	string	OPTIONAL
marriagePlace	The displayable label for the marriage place of the person.	string	OPTIONAL
ascendancyNumber	The context-specific ascendancy number for the person in relation to the other persons in the request. The ancestry number is defined using the Ahnentafel numbering system.	string	OPTIONAL
descendancyNumber	The context-specific descendancy number for the person in relation to the other persons in the request. The descendancy number is defined using the d'Aboville numbering system.	string	OPTIONAL
familiesAsParent	The views of the families of this person as a parent	List of `FamilyView`. Order is preserved.	OPTIONAL
familiesAsChild	The views of the families of this person as a child	List of `FamilyView`. Order is preserved.	OPTIONAL

2.2.1 The "DisplayProperties" XML Element

The gx:DisplayProperties XML type is used to (de)serialize the http://gedcomx.org/v1/DisplayProperties data type. The gx:display XML element is used to provide instances of the gx:DisplayProperties XML type as extension elements.

properties

name	description	XML property	XML type
name	The name of the person.	gx:name	xsd:string
gender	The displayable label for the gender of the person.	gx:gender	xsd:string
lifespan	The displayable label for the lifespan of the person.	gx:lifespan	xsd:string
birthDate	The displayable label for the birth date of the person.	gx:birthDate	xsd:string
birthPlace	The displayable label for the birth place of the person.	gx:birthPlace	xsd:string
deathDate	The displayable label for the death date of the person.	gx:deathDate	xsd:string
deathPlace	The displayable label for the death place of the person.	gx:deathPlace	xsd:string
marriageDate	The displayable label for the marriage date of the person.	gx:marriageDate	xsd:string
marriagePlace	The displayable label for the marriage place of the person.	gx:marriagePlace	xsd:string
ascendancyNumber	The context-specific ascendancy number for the person in relation to the other persons in the request. The ancestry number is defined using the Ahnentafel numbering system.	gx:ascendancyNumber	xsd:string
descendancyNumber	The context-specific descendancy number for the person in relation to the other persons in the request. The descendancy number is defined using the d'Aboville numbering system.	gx:descendancyNumber	xsd:string
familiesAsParent	The views of the families of this person as a parent	gx:familyAsParent	gx:FamilyView
familiesAsChild	The views of the families of this person as a child	gx:familyAsChild	gx:FamilyView

examples

<gx:display>
  <gx:name>...</gx:name>
  <gx:gender>...</gx:gender>
  <gx:lifespan>...</gx:lifespan>
  <gx:birthDate>...</gx:birthDate>
  <gx:birthPlace>...</gx:birthPlace>
  <gx:deathDate>...</gx:deathDate>
  <gx:deathPlace>...</gx:deathPlace>
  <gx:marriageDate>...</gx:marriageDate>
  <gx:marriagePlace>...</gx:marriagePlace>
  <gx:ascendancyNumber>...</gx:ascendancyNumber>
  <gx:descendancyNumber>...</gx:descendancyNumber>
  <gx:familyAsParent>...</gx:familyAsParent>
  <gx:familyAsParent>...</gx:familyAsParent>
  <gx:familyAsChild>...</gx:familyAsChild>
  <gx:familyAsChild>...</gx:familyAsChild>
  <!-- possibility of extension elements -->
</gx:display>

2.2.2 The "DisplayProperties" JSON Element

The DisplayProperties JSON type is used to (de)serialize the http://gedcomx.org/v1/DisplayProperties data type. The display JSON member is used to provide instances of the DisplayProperties JSON type as an extension element.

properties

name	description	JSON member	JSON object type
name	The name of the person.	name	string
gender	The displayable label for the gender of the person.	gender	string
lifespan	The displayable label for the lifespan of the person.	lifespan	string
birthDate	The displayable label for the birth date of the person.	birthDate	string
birthPlace	The displayable label for the birth place of the person.	birthPlace	string
deathDate	The displayable label for the death date of the person.	deathDate	string
deathPlace	The displayable label for the death place of the person.	deathPlace	string
marriageDate	The displayable label for the marriage date of the person.	marriageDate	string
marriagePlace	The displayable label for the marriage place of the person.	marriagePlace	string
ascendancyNumber	The context-specific ascendancy number for the person in relation to the other persons in the request. The ancestry number is defined using the Ahnentafel numbering system.	ascendancyNumber	string
descendancyNumber	The context-specific descendancy number for the person in relation to the other persons in the request. The descendancy number is defined using the d'Aboville numbering system.	descendancyNumber	string
familiesAsParent	The views of the families of this person as a parent	familiesAsParent	array of FamilyView
familiesAsChild	The views of the families of this person as a child	familiesAsChild	array of FamilyView

examples

"display" : {
  "name" : "...",
  "gender" : "...",
  "lifespan" : "...",
  "birthDate" : "...",
  "birthPlace" : "...",
  "deathDate" : "...",
  "deathPlace" : "...",
  "marriageDate" : "...",
  "marriagePlace" : "...",
  "ascendancyNumber" : "...",
  "descendancyNumber" : "...",
  "familiesAsParent" : [{ /*...*/ }, { /*...*/ }],
  "familiesAsChild" : [{ /*...*/ }, { /*...*/ }],
}

2.3 The "FamilyView" Data Type

The FamilyView data type defines a view of a family that consists of up to two parents and a list of children who have that set of parents in common. While the Relationship data type carries the canonical information about the nature of the relationship between the each pair of persons, the FamilyView is designed as a convenience for display purposes.

identifier

The identifier for the FamilyView data type is:

http://gedcomx.org/v1/FamilyView

properties

name	description	data type	constraints
parent1	Reference to a parent in the family.	URI	OPTIONAL. If provided, MUST resolve to an instance of `http://gedcomx.org/v1/Person`
parent2	Reference to a parent in the family.	URI	OPTIONAL. If provided, MUST resolve to an instance of `http://gedcomx.org/v1/Person`
children	List of references to the children in the family	List of URI	OPTIONAL. If provided, each element MUST resolve to an instance of `http://gedcomx.org/v1/Person`.

2.3.1 The "FamilyView" XML Element

The gx:FamilyView XML type is used to (de)serialize the http://gedcomx.org/v1/FamilyView data type. The gx:family XML element is used to provide instances of the gx:FamilyView XML type as extension elements.

properties

name	description	XML property	XML type
parent1	Reference to a parent in the family.	gx:parent1	gx:ResourceReference
parent2	Reference to a parent in the family.	gx:parent2	gx:ResourceReference
children	List of references to the children in the family.	gx:child	gx:ResourceReference

examples

<gx:family>
  <gx:parent1 resource="(uri reference to parent 1)"/>
  <gx:parent2 resource="(uri reference to parent 2)"/>
  <gx:child resource="(uri reference to child)"/>
  <gx:child resource="(uri reference to child)"/>
  <gx:child resource="(uri reference to child)"/>
  <!-- possibility of extension elements -->
</gx:family>

2.3.2 The "FamilyView" JSON Element

The FamilyView JSON type is used to (de)serialize the http://gedcomx.org/v1/FamilyView data type. The families JSON member is used to provide instances of the FamilyView JSON type as an extension element.

properties

name	description	JSON member	JSON object type
parent1	Reference to a parent in the family.	parent1	ResourceReference
parent2	Reference to a parent in the family.	parent2	ResourceReference
children	List of references to the children in the family.	children	array of ResourceReference](https://github.com/FamilySearch/gedcomx/blob/master/specifications/json-format-specification.md#resource-reference)

examples

"families" : [ {
  "parent1" :  {
    "resource" : "(uri reference to parent 1)"
  },
  "parent2" :  {
    "resource" : "(uri reference to parent 2)"
  },
  "children" : [ { "resource" : "(uri reference to child)" }, { "resource" : "(uri reference to child)" } ]
} ]

2.4 Identifier Types

The following additional identifier types are defined by GEDCOM X RS:

URI	description
`http://gedcomx.org/Persistent`	A persistent identifier for the resource. The value of the identifier MUST resolve to the instance of `Subject` to which the identifier applies. A persistent identifier is issued by a resource provider to support long-term access to the resource. A persistent identifier MAY conform to a specification, such as ARK.

2.5 The "PlaceDisplayProperties" Data Type

The PlaceDisplayProperties data type defines a set of properties for convenience in displaying a summary of a place to a user. All display property values are provided as appropriate for the locale requested by the consuming application, or the default locale if no locale was specified. Instances of PlaceDisplayProperties can be expected as extension elements to the PlaceDescription Data Type.

identifier

The identifier for the PlaceDisplayProperties data type is:

http://gedcomx.org/v1/PlaceDisplayProperties

properties

name	description	data type	constraints
name	A displayable name of the place.	string	OPTIONAL
fullName	The displayable label for the full name of the place.	string	OPTIONAL
type	The displayable label for the type of the place (city, country, etc.).	string	OPTIONAL

2.5.1 The "PlaceDisplayProperties" XML Element

The gx:PlaceDisplayProperties XML type is used to (de)serialize the http://gedcomx.org/v1/PlaceDisplayProperties data type. The gx:display XML element is used to provide instances of the gx:PlaceDisplayProperties XML type as extension elements.

properties

name	description	XML property	XML type
name	A displayable name of the place.	gx:name	xsd:string
fullName	The displayable label for the full name of the place.	gx:fullName	xsd:string
type	The displayable label for the type of the place (city, country, etc.).	gx:type	xsd:string

examples

<gx:display>
  <gx:name>...</gx:name>
  <gx:fullName>...</gx:fullName>
  <gx:type>...</gx:type>
  <!-- possibility of extension elements -->
</gx:display>

2.2.2 The "PlaceDisplayProperties" JSON Element

The PlaceDisplayProperties JSON type is used to (de)serialize the http://gedcomx.org/v1/PlaceDisplayProperties data type. The display JSON member is used to provide instances of the PlaceDisplayProperties JSON type as an extension element.

properties

name	description	JSON member	JSON object type
name	A displayable name of the place.	name	string
fullName	The displayable label for the full name of the place.	fullName	string
type	The displayable label for the type of the place (city, country, etc.).	type	string

examples

"display" : {
  "name" : "...",
  "fullName" : "...",
  "type" : "...",
}

3. Property Extensions

This section defines a set of extensions to data types already defined by the GEDCOM X Conceptual Model and and describes how the properties are included as extensions to GEDCOM X JSON and GEDCOM X XML.

3.1 Extensions to the "Date" Data Type

The following properties are defined as extensions to the Date Data Type:

name	description	data type	constraints
normalized	A list of normalized values for a date for display purposes.	List of `http://gedcomx.org/TextValue`. Order is preserved.	OPTIONAL. If more than one normalized value is provided, normalized values are assumed to be given in order of preference, with the most preferred normalized value in the first position in the list.

3.1.1 "Date" XML Type Extensions

name	XML property	XML type
normalized	gx:normalized	`gx:TextValue`

3.1.2 "Date" JSON Type Extensions

name	JSON member	JSON object type
normalized	normalized	array of `TextValue`

3.2 Extensions to the "PlaceReference" Data Type

The following properties are defined as extensions to the PlaceReference Data Type:

name	description	data type	constraints
normalized	A list of normalized values for a place for display purposes.	List of `http://gedcomx.org/TextValue`. Order is preserved.	OPTIONAL. If more than one normalized value is provided, normalized values are assumed to be given in order of preference, with the most preferred normalized value in the first position in the list.

3.2.1 "PlaceReference" XML Type Extensions

name	XML property	XML type
normalized	gx:normalized	`gx:TextValue`

3.2.2 "PlaceReference" JSON Type Extensions

name	JSON member	JSON object type
normalized	normalized	array of `TextValue`

3.3 Extensions to the "Name" Data Type

The following properties are defined as extensions to the Name Data Type:

name	description	data type	constraints
preferred	Whether the name is considered the "preferred" name for display purposes.	boolean	OPTIONAL

3.3.1 "Name" XML Type Extensions

name	XML property	XML type
preferred	preferred (attribute)	xsd:boolean

3.3.2 "Name" JSON Type Extensions

name	JSON member	JSON object type
preferred	preferred	boolean

3.4 Extensions to the "Person" Data Type

The following properties are defined as extensions to the Person Data Type:

name	description	data type	constraints
living	Whether the person is considered living by the application.	boolean	OPTIONAL
display	The display properties for the person.	`DisplayProperties`	OPTIONAL

3.4.1 "Person" XML Type Extensions

name	XML property	XML type
living	living (attribute)	xsd:boolean
display	gx:display	`DisplayProperties`

3.4.2 "Person" JSON Type Extensions

name	JSON member	JSON object type
living	living	boolean
display	display	`DisplayProperties`

3.5 The "sortKey" Property

A GEDCOM X application MAY define a relative sort order for types of resources in its data set. The "sortKey" property is used to provide this sort order by providing an alphanumeric value by which elements may be sorted relative to each other. The implementation details of the sort key are application-specific, and the sort key is only comparable to sort keys of elements of the same data type.

The "sortKey" property is defined as an extension to any data types that extend http://gedcomx.org/v1/Conclusion and to http://gedcomx.org/v1/SourceDescription.

3.5.1 "sortKey" XML Attribute

The sortKey is defined as an XML attribute of type xs:string on the applicable XML elements.

3.5.2 "sortKey" JSON Property

The sortKey is defined as a JSON member of type string on the applicable JSON objects.

3.6 The "resourceId" Property

A GEDCOM X application MAY choose to extend references to resources by providing an id of the resource being referenced using the "resourceId" property. The value and scope of the resource id is application-specific.

3.6.1 The "resourceId" XML Attribute

The resourceId is defined as an XML attribute of type xs:string. It is only applicable to the gx:ResourceReference XML type.

3.6.2 "resourceId" JSON Property

The resourceId is defined as a JSON member of type string. It is only applicable to the ResourceReference JSON type.

3.7 The "version" Property

A GEDCOM X application MAY choose to provide a version for a resource. The "version" property only applies to the http://gedcomx.org/v1/SourceDescription data type. The implementation of the version is application-specific.

3.7.1 The "version" XML Attribute

The version is defined as an XML attribute of type xs:string.

3.7.2 "resourceId" JSON Property

The version is defined as a JSON member of type string.

3.8 Extensions to the "PlaceDescription" Data Type

The following properties are defined as extensions to the PlaceDescription Data Type:

name	description	data type	constraints
display	The display properties for the place.	`PlaceDisplayProperties`	OPTIONAL

3.4.1 "PlaceDescription" XML Type Extensions

name	XML property	XML type
display	gx:display	`PlaceDisplayProperties`

3.4.2 "PlaceDescription" JSON Type Extensions

name	JSON member	JSON object type
display	display	`PlaceDisplayProperties`

4. Application States

This section defines a set of application states for a genealogical data application.

An "application state" is a snapshot of the state of genealogical data in an application at a specific point in time. The formal definition of an application state is comprised of the following components:

Applicable media types.
Implication of HTTP operations.
Expected data elements.
Transitions to other application states.
Embedded application states.
Removable components.

Applicable media types

Media types are used to represent the data elements of application states to the client. The client interprets the data according to the definition of the media type, and uses a media type to communicate changes of the application state to the server. The definition of each application state specifies the media types that servers are required to support. The definition of each application state also lists other media types that are optional.

Implication of HTTP operations

The definition of each application state includes how a given HTTP operation is expected to be interpreted by a server. Note that although this specification provides a discrete meaning to each HTTP operation for each application state, some HTTP operations are optional. If an application chooses to not support an optional operation, the server MUST respond with the HTTP 406 (Method Not Allowed) status code. Note that the OPTIONS and the HEAD operations are not defined explicitly by the definition of each application state. The HTTP specification already provides a sufficient definition of the OPTIONS and HEAD operations and their application is implicit in the definition of each application state.

Expected data elements

Each application state captures a specific set of data that is managed by the server. For example, the Person application state provides data about a person. The definition of each application state declares the data elements that client can expect. Note that the application server may choose to provide more data elements than those that are formally declared to be expected.

Transitions to other application states.

Each application state captures a limited portion of state. In order to enable the client to do useful things, controls are provided by each application state that describe the available choices to the client. For example, at a Person state, the client may want to read the children of the person, or it may want to read the spouses of a person, or it may want to update the name of the person, etc. The choices that are available to the client take the form of "transitions" to other application states.

The Link data type provides the controls to the client that declare the available state transitions. For a list of transitions defined by GEDCOM X RS, see Section 5, State Transitions.

Embedded application states.

Some state transitions are designated as transitions to "embedded" application states. Embedded application states are to be considered as components of the state from which the transition starts. The use of embedded application states is a common in online applications; an image embedded in an HTML page is an example.

Embedded application states are defined to accommodate designs of genealogical applications that break up a genealogical resource into multiple requests. For example, a server may choose to break up the Person state into two requests: one to get the conclusions of the person(name, gender, facts) and another one to get the source references of the person. One reason for such a design might be to target a specific caching strategy. Another reason might be to optimize requests for a specific database schema.

Section 6 (Embedding Application States) specifies how embedded application states are used.

Removable components

An application state may designate specific components that can be deleted. Examples of a removable component include the name of a person, a source reference, a role in an event, or a marriage fact of a couple relationship.

Removable components are designated in the same way as state transitions and embedded states, with a rel id and a target URI. An HTTP DELETE operation MAY be applied to the URI to remove the component from the application state.

4.1 The "Agent" State

The Agent application state consists of a single agent.

4.1.1 Media Types

Applications that implement the Agent state MUST support the application/x-gedcomx-v1+json media type as defined by the GEDCOM X JSON specification. Support for the application/x-gedcomx-v1+xml media type as defined by GEDCOM X XML is RECOMMENDED.

4.1.2 Operations

The following operations are defined as applicable to the Agent state:

operation	description	constraints
`GET`	Read an agent.	REQUIRED
`POST`	Update an agent.	OPTIONAL
`DELETE`	Delete an agent.	OPTIONAL

A successful GET request SHOULD result in a 200 response code.

A successful POST request SHOULD result in a 204 response code. See Section 8 (Updating Application States) for more information about updating application states.

A successful DELETE request SHOULD result in a 204 response code.

A server MAY provide other HTTP response codes as applicable under conditions established by the HTTP specification.

4.1.3 Data Elements

At least one instance of the Agent Data Type MUST be provided by the server in the successful response of a GET operation. If more than one instance of Agent is provided, the instance that represents the "main" agent MUST be provided as the first element in the list.

At least one instance of the Agent Data Type MUST be provided by the client in a request using the POST operation. If more than one instance of Agent is provided, the instance that represents the "main" agent MUST be provided as the first element in the list.

4.1.4 Transitions

No state transitions are specified for the Agent state.

4.1.5 Embedded States

No embedded states are specified for the Agent state.

4.1.6 Removable Components

No removable components are specified for the Agent state.

4.1.7 Example Requests

todo:

4.2 The "Ancestry Results" State

The Ancestry Results state consists of the results of a query for multiple generations of the ancestry of a person.

4.2.1 Media Types

Applications that implement the Ancestry Results state MUST support the application/x-gedcomx-v1+json media type as defined by the GEDCOM X JSON specification. Support for the application/x-gedcomx-v1+xml media type as defined by GEDCOM X XML is RECOMMENDED.

4.2.2 Operations

The following operations are defined as applicable to the Ancestry Results state:

operation	description	constraints
`GET`	Read the ancestry for a person.	REQUIRED

A successful GET request SHOULD result in a 200 response code.

A server MAY provide other HTTP response codes as applicable under conditions established by the HTTP specification.

4.2.3 Data Elements

The results of a successful query for the ancestry of a person MUST contain a list of instances of the Person Data Type. Each Person in the list MUST provide a value for the ascendancyNumber of the person using DisplayProperties.

4.2.4 Transitions

The following state transitions are specified for the Ancestry Results state:

rel	target state	scope	description
`person`	`Person` State	Each instance of `Person` Data Type	Transition from the ancestry results to the persons in the results.

Section 5, State Transitions defines other transitions that MAY be provided by the server for the Ancestry Results state. Even though other transitions are not formally included in the definition of the Ancestry Results state, use of other transitions is RECOMMENDED where applicable.

4.2.5 Embedded States

No embedded states are specified for the Ancestry Results state.

4.2.6 Removable Components

No removable components are specified for the Ancestry Results state.

4.2.7 Example Requests

todo:

4.3 The "Artifacts" State

The Artifacts state consists of a list of digital artifacts, such as images. Examples of usages of the Artifacts state include to list all the artifacts in a system or to provide a means for a client to upload artifacts in a system.

4.3.1 Media Types

Applications that implement the GET operation on the Artifacts state MUST support the application/x-gedcomx-v1+json media type as defined by the GEDCOM X JSON specification. Support for the application/x-gedcomx-v1+xml media type as defined by GEDCOM X XML is RECOMMENDED.

Applications that implement the POST operation on the Artifacts state MUST support the multipart/form-data media type as defined by RFC 2388.

4.3.2 Operations

The following operations are defined as applicable to the Artifacts state:

operation	description	constraints
`GET`	Read a list of artifacts as source descriptions.	OPTIONAL
`POST`	Upload an artifact.	OPTIONAL

A successful GET request SHOULD result in a 200 response code, if the list contains one or more artifacts. If the list is empty, a successful GET SHOULD result in a 204 response code.

A successful POST request, the request SHOULD result in a 201 response code and a Location header specifying the URI of the description of the created artifact.

A server MAY provide other HTTP response codes as applicable under conditions established by the HTTP specification.

4.3.3 Data Elements

A list of instances of the SourceDescription Data Type. MUST be provided by the server in the successful response of a GET operation. If the list of source descriptions is large, the server MAY break up the list into multiple pages according to Section 7, Paged Application States.

A single digital artifact and its associated metadata MUST be provided by the client in a request using the POST operation. The artifact and metadata is provided as form-data parameters defined as follows:

parameter name	description
`artifact`	The bytes of the artifact.
`title`	A title for the artifact.
`description`	A description for the artifact.
`citation`	A citation for the artifact.

4.3.4 Transitions

The following state transitions are specified for the Artifacts state:

rel	target state	scope	description
`description`	`Source Description` State	Each instance of `Source Description` Data Type	Transition from the list of sources descriptions to a single source description.

Section 5, State Transitions defines other transitions that MAY be provided by the server for the Source Descriptions state. Even though other transitions are not formally included in the definition of the Source Descriptions state, use of other transitions is RECOMMENDED where applicable.

4.3.5 Embedded States

No embedded states are specified for the Artifacts state.

4.3.6 Removable Components

No removable components are specified for the Artifacts state.

4.3.7 Example Requests

todo:

4.4 The "Collections" State

The Collections state consists of a list of collections. Examples of usages of the Collections state include to provide a list of subcollections of a collection, or to list all the collections in a system, or to provide a means for a client to create a collection in a system.

4.4.1 Media Types

Applications that implement the Collections state MUST support the application/x-gedcomx-v1+json media type as defined by the GEDCOM X JSON specification. Support for the application/x-gedcomx-v1+xml media type as defined by GEDCOM X XML is RECOMMENDED.

Applications that implement the Collections state MUST support the GEDCOM X Record Extensions.

4.4.2 Operations

The following operations are defined as applicable to the Collections state:

operation	description	constraints
`GET`	Read a list of collections.	OPTIONAL
`POST`	Create a collection or set of collections.	OPTIONAL

A successful GET request SHOULD result in a 200 response code, if the list contains one or more collections. If the list is empty, a successful GET SHOULD result in a 204 response code.

If one (and only one) collection was created as a result of a successful POST request, the request SHOULD result in a 201 response code and a Location header specifying the URI of the created collection. If multiple collections were created as a result of a successful POST request, the request SHOULD result in a 204 response code.

A server MAY provide other HTTP response codes as applicable under conditions established by the HTTP specification.

4.4.3 Data Elements

A list of instances of the Collection Data Type. MUST be provided by the server in the successful response of a GET operation. If the list of collections is large, the server MAY break up the list into multiple pages according to Section 7, Paged Application States.

A list of instances of the Collection Data Type. MUST be provided by the client in a request using the POST operation. The server considers each instance of Collection provided by the client as a candidate to be created and added to the list of collections.

4.4.4 Transitions

The following state transitions are specified for the Collections state:

rel	target state	scope	description
`collection`	`Collection` State	Each instance of `Collection` Data Type	Transition from the list of collections to a single collection.

Section 5, State Transitions defines other transitions that MAY be provided by the server for the Collections state. Even though other transitions are not formally included in the definition of the Collections state, use of other transitions is RECOMMENDED where applicable.

4.4.5 Embedded States

No embedded states are specified for the Collections state.

4.4.6 Removable Components

No removable components are specified for the Collections state.

4.4.7 Example Requests

todo:

4.5 The "Collection" State

The Collection application state consists of a single collection.

4.5.1 Media Types

Applications that implement the Collection state MUST support the application/x-gedcomx-v1+json media type as defined by the GEDCOM X JSON specification. Support for the application/x-gedcomx-v1+xml media type as defined by GEDCOM X XML is RECOMMENDED.

Applications that implement the Collection state MUST support the GEDCOM X Record Extensions.

4.5.2 Operations

The following operations are defined as applicable to the Collection state:

operation	description	constraints
`GET`	Read a collection.	REQUIRED
`POST`	Update a collection.	OPTIONAL
`DELETE`	Delete a collection.	OPTIONAL

A successful GET request SHOULD result in a 200 response code.

A successful POST request SHOULD result in a 204 response code. See Section 8 (Updating Application States) for more information about updating application states.

A successful DELETE request SHOULD result in a 204 response code.

A server MAY provide other HTTP response codes as applicable under conditions established by the HTTP specification.

4.5.3 Data Elements

At least one instance of the Collection Data Type MUST be provided by the server in the successful response of a GET operation. If more than one instance of Collection is provided, the instance that represents the "main" collection MUST be provided as the first element in the list.

At least one instance of the Collection Data Type MUST be provided by the client in a request using the POST operation. If more than one instance of Collection is provided, the instance that represents the "main" collection MUST be provided as the first element in the list.

4.5.4 Transitions

rel	target state	scope	description
`collection`	`Collection` State	`Collection` Data Type	Self-link to the `Collection` state.
`current-user-person`	`Person` State	`Collection` Data Type	Link to the person in the collection representing the current user.
`current-user-resources`	`Source Descriptions` State	`Collection` Data Type	Link to a list of resources in the collection that are owned by or otherwise associated with the current user, described as sources.
`subcollections`	`Collections` State	`Collection` Data Type	Link to the list of subcollections for this collection.
`persons`	`Persons` State	`Collection` Data Type	Link to the list of persons in the collection.
`relationships`	`Relationships` State	`Collection` Data Type	Link to the list of relationships between persons in this collection.
`events`	`Events` State	`Collection` Data Type	Link to the list of events in this collection.
`records`	`Records` State	`Collection` Data Type	Link to the list of records in the collection.
`artifacts`	`Artifacts` State	`Collection` Data Type	Link to the list of digital artifacts in the collection.
`source-descriptions`	`Source Descriptions` State	`Collection` Data Type	Link to the list of sources described in the collection.
`person-search`	`Person Search Results` State	`Collection` Data Type	Templated Link to the query used to search for persons in the system.
`place-search`	`Place Search Results` State	`Collection` Data Type	Templated Link to the query used to search for places in the system.
`http://oauth.net/core/2.0/endpoint/authorize`	OAuth 2 Authorization Page	`Collection` Data Type	Link to the authorization page used by a user to authenticate to the system. See Section 9, Authentication and Authorization.
`http://oauth.net/core/2.0/endpoint/token`	OAuth 2 Token	`Collection` Data Type	Link to the endpoint used to obtain an access token. See Section 9, Authentication and Authorization.

Section 5, State Transitions defines other transitions that MAY be provided by the server for the Collection state. Even though other transitions are not formally included in the definition of the Collection state, use of other transitions is RECOMMENDED where applicable.

4.5.5 Embedded States

No embedded states are specified for the Collection state.

4.5.6 Removable Components

No removable components are specified for the Collection state.

4.5.7 Example Requests

todo:

4.6 The "Descendancy Results" State

The Descendancy Results state consists of the results of a query for multiple generations of the descendancy of a person.

4.6.1 Media Types

Applications that implement the Descendancy Results state MUST support the application/x-gedcomx-v1+json media type as defined by the GEDCOM X JSON specification. Support for the application/x-gedcomx-v1+xml media type as defined by GEDCOM X XML is RECOMMENDED.

4.6.2 Operations

The following operations are defined as applicable to the Descendancy Results state:

operation	description	constraints
`GET`	Read the descendancy for a person.	REQUIRED

A successful GET request SHOULD result in a 200 response code.

A server MAY provide other HTTP response codes as applicable under conditions established by the HTTP specification.

4.6.3 Data Elements

The results of a successful query for the ancestry of a person MUST contain a list of instances of the Person Data Type. Each Person in the list MUST provide a value for the descendancyNumber of the person using DisplayProperties.

4.6.4 Transitions

The following state transitions are specified for the Descendancy Results state:

rel	target state	scope	description
`person`	`Person` State	Each instance of `Person` Data Type	Transition from the descendancy results to the persons in the results.

Section 5, State Transitions defines other transitions that MAY be provided by the server for the Descendancy Results state. Even though other transitions are not formally included in the definition of the Descendancy Results state, use of other transitions is RECOMMENDED where applicable.

4.6.5 Embedded States

No embedded states are specified for the Descendancy Results state.

4.6.6 Removable Components

No removable components are specified for the Descendancy Results state.

4.6.7 Example Requests

todo:

4.7 The "Events" State

The Events state consists of a list of events. Examples of usages of the Events state include to list all the events in a system or to provide a means for a client to create a event in a system.

4.7.1 Media Types

Applications that implement the Events state MUST support the application/x-gedcomx-v1+json media type as defined by the GEDCOM X JSON specification. Support for the application/x-gedcomx-v1+xml media type as defined by GEDCOM X XML is RECOMMENDED.

4.7.2 Operations

The following operations are defined as applicable to the Events state:

operation	description	constraints
`GET`	Read a list of events.	OPTIONAL
`POST`	Create an event or set of events.	OPTIONAL

A successful GET request SHOULD result in a 200 response code, if the list contains one or more events. If the list is empty, a successful GET SHOULD result in a 204 response code.

If one (and only one) event was created as a result of a successful POST request, the request SHOULD result in a 201 response code and a Location header specifying the URI of the created event. If multiple events were created as a result of a successful POST request, the request SHOULD result in a 204 response code.

A server MAY provide other HTTP response codes as applicable under conditions established by the HTTP specification.

4.7.3 Data Elements

A list of instances of the Event Data Type. MUST be provided by the server in the successful response of a GET operation. If the list of events is large, the server MAY break up the list into multiple pages according to Section 7, Paged Application States.

A list of instances of the Event Data Type. MUST be provided by the client in a request using the POST operation. The server considers each instance of Event provided by the client as a candidate to be created and added to the list of events.

4.7.4 Transitions

The following state transitions are specified for the Events state:

rel	target state	scope	description
`event`	`Event` State	Each instance of `Event` Data Type	Transition from the list of events to a single event.

Section 5, State Transitions defines other transitions that MAY be provided by the server for the Events state. Even though other transitions are not formally included in the definition of the Events state, use of other transitions is RECOMMENDED where applicable.

4.7.5 Embedded States

No embedded states are specified for the Events state.

4.7.6 Removable Components

No removable components are specified for the Events state.

4.7.7 Example Requests

todo:

4.8 The "Event" State

The Event application state consists of a single event.

4.8.1 Media Types

Applications that implement the Event state MUST support the application/x-gedcomx-v1+json media type as defined by the GEDCOM X JSON specification. Support for the application/x-gedcomx-v1+xml media type as defined by GEDCOM X XML is RECOMMENDED.

4.8.2 Operations

The following operations are defined as applicable to the Event state:

operation	description	constraints
`GET`	Read an event.	REQUIRED
`POST`	Update an event.	OPTIONAL
`DELETE`	Delete an event.	OPTIONAL

A successful GET request SHOULD result in a 200 response code.

A successful POST request SHOULD result in a 204 response code. See Section 8 (Updating Application States) for more information about updating application states.

A successful DELETE request SHOULD result in a 204 response code.

A server MAY provide other HTTP response codes as applicable under conditions established by the HTTP specification.

4.8.3 Data Elements

At least one instance of the Event Data Type MUST be provided by the server in the successful response of a GET operation. If more than one instance of Event is provided, the instance that represents the "main" event MUST be provided as the first element in the list.

At least one instance of the Event Data Type MUST be provided by the client in a request using the POST operation. If more than one instance of Event is provided, the instance that represents the "main" event MUST be provided as the first element in the list.

4.8.4 Transitions

rel	target state	scope	description
`event`	`Event` State	`Event` Data Type	Self-link to the `Event` state.

4.8.5 Embedded States

No embedded states are specified for the Event state.

4.8.6 Removable Components

The following components of the Event state MAY be designated by the server as removable:

rel	scope	description
`role`	Each instance of `Event Role` Data Type	The link used to remove the component.

A successful DELETE request to the removable component SHOULD result in a 204 response code.

4.8.7 Example Requests

todo:

4.9 The "Persons" State

The Persons state consists of a list of persons. Examples of usages of the Persons state include to provide a list of all the persons in a collection, or to provide a means for a client to create a person in a collection.

4.9.1 Media Types

Applications that implement the Persons state MUST support the application/x-gedcomx-v1+json media type as defined by the GEDCOM X JSON specification. Support for the application/x-gedcomx-v1+xml media type as defined by GEDCOM X XML is RECOMMENDED.

4.9.2 Operations

The following operations are defined as applicable to the Persons state:

operation	description	constraints
`GET`	Read a list of persons.	OPTIONAL
`POST`	Create a person or set of persons.	OPTIONAL

A successful GET request SHOULD result in a 200 response code, if the list contains one or more persons. If the list is empty, a successful GET SHOULD result in a 204 response code.

If one (and only one) person was created as a result of a successful POST request, the request SHOULD result in a 201 response code and a Location header specifying the URI of the created person. If multiple persons were created as a result of a successful POST request, the request SHOULD result in a 204 response code.

A server MAY provide other HTTP response codes as applicable under conditions established by the HTTP specification.

4.9.3 Data Elements

A list of instances of the Person Data Type. MUST be provided by the server in the successful response of a GET operation. If the list of persons is large, the server MAY break up the list into multiple pages according to Section 7, Paged Application States.

A list of instances of the Person Data Type. MUST be provided by the client in a request using the POST operation. The server considers each instance of Person provided by the client as a candidate to be created and added to the list of persons.

4.9.4 Transitions

The following state transitions are specified for the Persons state:

rel	target state	scope	description
`person`	`Person` State	Each instance of `Person` Data Type	Transition from the list of persons to a single person.

Section 5, State Transitions defines other transitions that MAY be provided by the server for the Persons state. Even though other transitions are not formally included in the definition of the Persons state, use of other transitions is RECOMMENDED where applicable.

4.9.5 Embedded States

No embedded states are specified for the Persons state.

4.9.6 Removable Components

No removable components are specified for the Persons state.

4.9.7 Example Requests

todo:

4.10 The "Person" State

The Person application state consists of a single person.

4.10.1 Media Types

Applications that implement the Person state MUST support the application/x-gedcomx-v1+json media type as defined by the GEDCOM X JSON specification. Support for the application/x-gedcomx-v1+xml media type as defined by GEDCOM X XML is RECOMMENDED.

4.10.2 Operations

The following operations are defined as applicable to the Person state:

operation	description	constraints
`GET`	Read a person.	REQUIRED
`POST`	Update a person.	OPTIONAL
`DELETE`	Delete a person.	OPTIONAL

A successful GET request SHOULD result in a 200 response code.

A successful POST request SHOULD result in a 204 response code. See Section 8 (Updating Application States) for more information about updating application states.

A successful DELETE request SHOULD result in a 204 response code.

A server MAY provide other HTTP response codes as applicable under conditions established by the HTTP specification.

4.10.3 Data Elements

At least one instance of the Person Data Type MUST be provided by the server in the successful response of a GET operation. If more than one instance of Person is provided, the instance that represents the "main" person MUST be provided as the first element in the list.

At least one instance of the Person Data Type MUST be provided by the client in a request using the POST operation. If more than one instance of Person is provided, the instance that represents the "main" person MUST be provided as the first element in the list.

4.10.4 Transitions

rel	target state	scope	description
`person`	`Person` State	`Person` Data Type	Self-link to the `Person` state.
`collection`	`Collection` State	`Person` Data Type	Link to the collection that contains this person.
`parents`	`Person Parents` State	`Person` Data Type	Link to the list of parents for this person.
`children`	`Person Children` State	`Person` Data Type	Link to the list of children for this person.
`spouses`	`Person Spouses` State	`Person` Data Type	Link to the list of spouses for this person.
`ancestry`	`Ancestry` State	`Person` Data Type	Link to the ancestry query for this person.
`descendancy`	`Descendancy` State	`Person` Data Type	Link to the descendancy query for this person.
`http://oauth.net/core/2.0/endpoint/authorize`	OAuth 2 Authorization Page	`Person` Data Type	Link to the authorization page used by a user to authenticate to the system. See Section 9, Authentication and Authorization.
`http://oauth.net/core/2.0/endpoint/token`	OAuth 2 Token	`Person` Data Type	Link to the endpoint used to obtain an access token. See Section 9, Authentication and Authorization.

Section 5, State Transitions defines other transitions that MAY be provided by the server for the Person state. Even though other transitions are not formally included in the definition of the Person state, use of other transitions is RECOMMENDED where applicable.

4.10.5 Embedded States

The following embedded states are specified for the Person state.

rel	scope	description
`child-relationships`	`Person` Data Type	List of relationships to children on the person. If no link to `child-relationships` is provided, the list of child relationships MUST be included in the original request for the `Person` state.
`parent-relationships`	`Person` Data Type	List of relationships to parents on the person. If no link to `parent-relationships` is provided, the list of parent relationships MUST be included in the original request for the `Person` state.
`spouse-relationships`	`Person` Data Type	List of relationships to spouses on the person. If no link to `spouse-relationships` is provided, the list of spouse relationships MUST be included in the original request for the `Person` state.
`conclusions`	`Person` Data Type	List of conclusions (names, gender, facts) for the person. If no link to `conclusions` is provided, the list of conclusions MUST be included in the original request for the `Person` state. If a link to `conclusions` is provided, this link SHOULD be used to create new conclusionss or update existing conclusions with a `POST` request.
`evidence-references`	`Person` Data Type	List of evidence (persona) references for the person. If no link to `evidence-references` is provided, the list of evidence references MUST be included in the original request for the `Person` state. If a link to `evidence-references` is provided, this link SHOULD be used to create new evidence references or update existing evidence references with a `POST` request.
`media-references`	`Person` Data Type	List of media references for the person. If no link to `media-references` is provided, the list of media references MUST be included in the original request for the `Person` state. If a link to `media-references` is provided, this link SHOULD be used to create new media references or update existing media references with a `POST` request.
`notes`	`Person` Data Type	List of notes for the person. If no link to `notes` is provided, the list of notes MUST be included in the original request for the `Person` state. If a link to `notes` is provided, this link SHOULD be used to create new notes or update existing notes with a `POST` request.
`source-references`	`Person` Data Type	List of source references for the person. If no link to `source-references` is provided, the list of source references MUST be included in the original request for the `Person` state. If a link to `source-references` is provided, this link SHOULD be used to create new source references or update existing source references with a `POST` request.

4.10.6 Removable Components

The following components of the Person state MAY be designated by the server as removable:

rel	scope	description
`conclusion`	Each instance of `Fact` Data Type, `Gender` Data Type, and `Name` Data Type	The link used to remove the fact, gender, or name.
`evidence-reference`	Each instance of `EvidenceReference` Data Type	The link used to remove the persona (evidence) reference.
`media-reference`	Each instance of `SourceReference` Data Type	The link used to remove the media reference.
`note`	Each instance of `Note` Data Type	The link used to remove the note.
`source-reference`	Each instance of `SourceReference` Data Type	The link used to remove the source reference.

A successful DELETE request to the removable component SHOULD result in a 204 response code.

4.10.7 Example Requests

todo:

4.11 The "Person Search Results" State

The Person Search Results state consists of the results of a search query for persons in the system.

4.11.1 Media Types

Applications that implement the Person Search Results state MUST support the application/x-gedcomx-atom+json media type as defined by the GEDCOM X Atom Extensions specification. Support for the application/atom+xml media type as defined by RFC 4287 (The Atom Syndication Format) is RECOMMENDED.

4.11.2 Operations

The following operations are defined as applicable to the Person Search Results state:

operation	description	constraints
`GET`	Search for persons.	REQUIRED

A successful GET request SHOULD result in a 200 response code, if the search results contain one or more persons. If the search results are empty, a successful GET SHOULD result in a 204 response code. If the list of results is large, the server MAY break up the list into multiple pages according to Section 7, Paged Application States.

4.11.3 Data Elements

The results of a successful query for the ancestry of a person MUST contain a list of entries that each describe a person. The content of each entry is a GEDCOM X document that MUST contain at least one instance of the Person Data Type. If more than one instance of Person is provided, the instance that represents the "main" person for the result MUST be provided as the first element in the list. Other elements might include relatives of the person and/or their relationships.

4.11.4 Transitions

The following state transitions are specified for the Person Search Results state:

rel	target state	scope	description
`person`	`Person` State	Each instance of `Entry` Data Type as specified by RFC 4287	Transition from the search results to the persons in the results.

Section 5, State Transitions defines other transitions that MAY be provided by the server for the Person Search Results state. Even though other transitions are not formally included in the definition of the Person Search Results state, use of other transitions is RECOMMENDED where applicable.

4.11.5 Embedded States

No embedded states are specified for the Person Search Results state.

4.11.6 Removable Components

No removable components are specified for the Person Search Results state.

4.11.7 Example Requests

todo:

4.12 The "Person Children" State

The Person Children state consists of a list of children for a specific person.

4.12.1 Media Types

Applications that implement the Person Children state MUST support the application/x-gedcomx-v1+json media type as defined by the GEDCOM X JSON specification. Support for the application/x-gedcomx-v1+xml media type as defined by GEDCOM X XML is RECOMMENDED.

4.12.2 Operations

The following operations are defined as applicable to the Person Children state:

operation	description	constraints
`GET`	Read the list of children of a person.	REQUIRED

A successful GET request SHOULD result in a 200 response code, if the list contains one or more persons. If the list is empty, a successful GET SHOULD result in a 204 response code.

A server MAY provide other HTTP response codes as applicable under conditions established by the HTTP specification.

4.12.3 Data Elements

A list of instances of the Person Data Type MUST be provided by the server in the successful response of a GET operation. A list of instances of the Relationship Data Type describing the relationships to each child SHOULD be provided by the server in the successful response of a GET operation.

4.12.4 Transitions

The following state transitions are specified for the Person Children state:

rel	target state	scope	description
`person`	`Person` State	Each instance of `Person` Data Type	Transition from the list of persons to a single person.

Section 5, State Transitions defines other transitions that MAY be provided by the server for the Person Children state. Even though other transitions are not formally included in the definition of the Person Children state, use of other transitions is RECOMMENDED where applicable.

4.12.5 Embedded States

No embedded states are specified for the Person Children state.

4.12.6 Removable Components

No removable components are specified for the Person Children state.

4.12.7 Example Requests

todo:

4.13 The "Person Spouses" State

The Person Spouses state consists of a list of spouses for a specific person.

4.13.1 Media Types

Applications that implement the Person Spouses state MUST support the application/x-gedcomx-v1+json media type as defined by the GEDCOM X JSON specification. Support for the application/x-gedcomx-v1+xml media type as defined by GEDCOM X XML is RECOMMENDED.

4.13.2 Operations

The following operations are defined as applicable to the Person Spouses state:

operation	description	constraints
`GET`	Read the list of spouses of a person.	REQUIRED

A successful GET request SHOULD result in a 200 response code, if the list contains one or more persons. If the list is empty, a successful GET SHOULD result in a 204 response code.

A server MAY provide other HTTP response codes as applicable under conditions established by the HTTP specification.

4.13.3 Data Elements

A list of instances of the Person Data Type. MUST be provided by the server in the successful response of a GET operation. A list of instances of the Relationship Data Type describing the relationships to each spouse SHOULD be provided by the server in the successful response of a GET operation.

4.13.4 Transitions

The following state transitions are specified for the Person Spouses state:

rel	target state	scope	description
`person`	`Person` State	Each instance of `Person` Data Type	Transition from the list of persons to a single person.

Section 5, State Transitions defines other transitions that MAY be provided by the server for the Person Spouses state. Even though other transitions are not formally included in the definition of the Person Spouses state, use of other transitions is RECOMMENDED where applicable.

4.13.5 Embedded States

No embedded states are specified for the Person Spouses state.

4.13.6 Removable Components

No removable components are specified for the Person Spouses state.

4.13.7 Example Requests

todo:

4.14 The "Person Parents" State

The Person Parents state consists of a list of parents for a specific person.

4.14.1 Media Types

Applications that implement the Person Parents state MUST support the application/x-gedcomx-v1+json media type as defined by the GEDCOM X JSON specification. Support for the application/x-gedcomx-v1+xml media type as defined by GEDCOM X XML is RECOMMENDED.

4.14.2 Operations

The following operations are defined as applicable to the Person Parents state:

operation	description	constraints
`GET`	Read the list of parents of a person.	REQUIRED

A successful GET request SHOULD result in a 200 response code, if the list contains one or more persons. If the list is empty, a successful GET SHOULD result in a 204 response code.

A server MAY provide other HTTP response codes as applicable under conditions established by the HTTP specification.

4.14.3 Data Elements

A list of instances of the Person Data Type. MUST be provided by the server in the successful response of a GET operation. A list of instances of the Relationship Data Type describing the relationships to each parent SHOULD be provided by the server in the successful response of a GET operation.

4.14.4 Transitions

The following state transitions are specified for the Person Parents state:

rel	target state	scope	description
`person`	`Person` State	Each instance of `Person` Data Type	Transition from the list of persons to a single person.

Section 5, State Transitions defines other transitions that MAY be provided by the server for the Person Parents state. Even though other transitions are not formally included in the definition of the Person Parents state, use of other transitions is RECOMMENDED where applicable.

4.14.5 Embedded States

No embedded states are specified for the Person Parents state.

4.14.6 Removable Components

No removable components are specified for the Person Parents state.

4.14.7 Example Requests

todo:

4.15 The "Place Descriptions" State

The Place Descriptions state consists of a list of place descriptions. Examples of usages of the Place Descriptions state include listing all the descriptions of places in a system or providing a means for a client to create place description in a system.

4.15.1 Media Types

Applications that implement the Place Descriptions state MUST support the application/x-gedcomx-v1+json media type as defined by the GEDCOM X JSON specification. Support for the application/x-gedcomx-v1+xml media type as defined by GEDCOM X XML is RECOMMENDED.

4.15.2 Operations

The following operations are defined as applicable to the Place Descriptions state:

operation	description	constraints
`GET`	Read a list of place descriptions.	OPTIONAL
`POST`	Create an event or set of place descriptions.	OPTIONAL

A successful GET request SHOULD result in a 200 response code, if the list contains one or more place descriptions. If the list is empty, a successful GET SHOULD result in a 204 response code.

If one (and only one) event was created as a result of a successful POST request, the request SHOULD result in a 201 response code and a Location header specifying the URI of the created place description. If multiple place descriptions were created as a result of a successful POST request, the request SHOULD result in a 204 response code.

A server MAY provide other HTTP response codes as applicable under conditions established by the HTTP specification.

4.15.3 Data Elements

A list of instances of the PlaceDescription Data Type. MUST be provided by the server in the successful response of a GET operation. If the list of place descriptions is large, the server MAY break up the list into multiple pages according to Section 7, Paged Application States.

A list of instances of the PlaceDescription Data Type. MUST be provided by the client in a request using the POST operation. The server considers each instance of PlaceDescription provided by the client as a candidate to be created and added to the list of place descriptions.

4.15.4 Transitions

The following state transitions are specified for the Place Descriptions state:

rel	target state	scope	description
`description`	`Place Description` State	Each instance of `Place Description` Data Type	Transition from the list of places descriptions to a single place description.

Section 5, State Transitions defines other transitions that MAY be provided by the server for the Place Descriptions state. Even though other transitions are not formally included in the definition of the Place Descriptions state, use of other transitions is RECOMMENDED where applicable.

4.15.5 Embedded States

No embedded states are specified for the Place Descriptions state.

4.15.6 Removable Components

No removable components are specified for the Place Descriptions state.

4.15.7 Example Requests

todo:

4.16 The "Place Description" State

The Place Description application state consists of a single description of a place.

4.16.1 Media Types

Applications that implement the Place Description state MUST support the application/x-gedcomx-v1+json media type as defined by the GEDCOM X JSON specification. Support for the application/x-gedcomx-v1+xml media type as defined by GEDCOM X XML is RECOMMENDED.

4.16.2 Operations

The following operations are defined as applicable to the Place Description state:

operation	description	constraints
`GET`	Read a place description.	REQUIRED
`POST`	Update a place description.	OPTIONAL
`DELETE`	Delete a place description.	OPTIONAL

A successful GET request SHOULD result in a 200 response code.

A successful POST request SHOULD result in a 204 response code. See Section 8 (Updating Application States) for more information about updating application states.

A successful DELETE request SHOULD result in a 204 response code.

A server MAY provide other HTTP response codes as applicable under conditions established by the HTTP specification.

4.16.3 Data Elements

At least one instance of the PlaceDescription Data Type MUST be provided by the server in the successful response of a GET operation. If more than one instance of PlaceDescription is provided, the instance that represents the "main" place description MUST be provided as the first element in the list.

At least one instance of the PlaceDescription Data Type MUST be provided by the client in a request using the POST operation.

4.16.4 Transitions

rel	target state	scope	description
`description`	`Place Description` State	Each instance of `Place Description` Data Type	Self-link to the place description.

4.16.5 Embedded States

No embedded states are specified for the Place Description state.

4.16.6 Removable Components

No removable components are specified for the Place Description state.

4.16.7 Example Requests

todo:

4.17 The "Place Search Results" State

The Place Search Results state consists of the results of a search query for places in the system.

4.17.1 Media Types

Applications that implement the Place Search Results state MUST support the application/x-gedcomx-atom+json media type as defined by the GEDCOM X Atom Extensions specification. Support for the application/atom+xml media type as defined by RFC 4287 (The Atom Syndication Format) is RECOMMENDED.

4.17.2 Operations

The following operations are defined as applicable to the Place Search Results state:

operation	description	constraints
`GET`	Search for places.	REQUIRED

A successful GET request SHOULD result in a 200 response code, if the search results contain one or more places. If the search results are empty, a successful GET SHOULD result in a 204 response code. If the list of results is large, the server MAY break up the list into multiple pages according to Section 7, Paged Application States.

4.17.3 Data Elements

The results of a successful query for the ancestry of a place MUST contain a list of entries that each describe a place. The content of each entry is a GEDCOM X document that MUST contain at least one instance of the PlaceDescription Data Type If more than one instance of PlaceDescription is provided, the instance that represents the "main" place for the result MUST be provided as the first element in the list.

4.17.4 Transitions

The following state transitions are specified for the Place Search Results state:

rel	target state	scope	description
`description`	`Place Description` State	Each instance of `Entry` Data Type as specified by RFC 4287	Transition from the search results to the descriptions of the places in the results.

Section 5, State Transitions defines other transitions that MAY be provided by the server for the Place Search Results state. Even though other transitions are not formally included in the definition of the Place Search Results state, use of other transitions is RECOMMENDED where applicable.

4.17.5 Embedded States

No embedded states are specified for the Place Search Results state.

4.17.6 Removable Components

No removable components are specified for the Place Search Results state.

4.17.7 Example Requests

todo:

4.18 The "Records" State

The Records state consists of a list of records.

4.18.1 Media Types

Applications that implement the Records state MUST support the application/x-gedcomx-atom+json media type as defined by the GEDCOM X Atom Extensions specification. Support for the application/atom+xml media type as defined by RFC 4287 (The Atom Syndication Format) is RECOMMENDED.

Applications that implement the Records state MUST support the GEDCOM X Record Extensions.

4.18.2 Operations

The following operations are defined as applicable to the Records state:

operation	description	constraints
`GET`	Read a list of records.	REQUIRED

A successful GET request SHOULD result in a 200 response code, if the list contains one or more records. If the list is empty, a successful GET SHOULD result in a 204 response code.

A server MAY provide other HTTP response codes as applicable under conditions established by the HTTP specification.

4.18.3 Data Elements

The results of a successful query for the ancestry of a person MUST contain a list of entries that each describe a person. The content of each entry is a GEDCOM X document that contains the data of the record.

4.18.4 Transitions

The following state transitions are specified for the Records state:

rel	target state	scope	description
`record`	`Record` State	Each instance of `Entry` Data Type as specified by RFC 4287	Transition from the list of records to the a specific record.

Section 5, State Transitions defines other transitions that MAY be provided by the server for the Records state. Even though other transitions are not formally included in the definition of the Records state, use of other transitions is RECOMMENDED where applicable.

4.18.5 Embedded States

No embedded states are specified for the Records state.

4.18.6 Removable Components

No removable components are specified for the Records state.

4.18.7 Example Requests

todo:

4.19 The "Record" State

The Record application state consists of a single record.

4.19.1 Media Types

Applications that implement the Record state MUST support the application/x-gedcomx-v1+json media type as defined by the GEDCOM X JSON specification. Support for the application/x-gedcomx-v1+xml media type as defined by GEDCOM X XML is RECOMMENDED.

4.19.2 Operations

The following operations are defined as applicable to the Record state:

operation	description	constraints
`GET`	Read a record.	REQUIRED
`POST`	Update a record.	OPTIONAL
`DELETE`	Delete a record.	OPTIONAL

A successful GET request SHOULD result in a 200 response code.

A successful POST request SHOULD result in a 204 response code. See Section 8 (Updating Application States) for more information about updating application states.

A successful DELETE request SHOULD result in a 204 response code.

A server MAY provide other HTTP response codes as applicable under conditions established by the HTTP specification.

4.19.3 Data Elements

The GEDCOM X document that is provided by the Record state contains the data that is extracted from the record. Expected elements include persons, relationships, events, and source descriptions.

4.19.4 Transitions

rel	target state	scope	description
`record`	`Record` State	GEDCOM X Document	Self-link to the `Record` state.
`person`	`Person` State	`Person` Data Type	Link to a specific person.
`relationship`	`Relationship` State	`Relationship` Data Type	Link to a specific relationship.
`event`	`Event` State	`Event` Data Type	Link to a specific event.
`description`	`Source Description` State	`SourceDescription` Data Type	Link to a specific source description.
`description`	`Place Description` State	`PlaceDescription` Data Type	Link to a specific place description.
`http://oauth.net/core/2.0/endpoint/authorize`	OAuth 2 Authorization Page	`Record` Data Type	Link to the authorization page used by a user to authenticate to the system. See Section 9, Authentication and Authorization.
`http://oauth.net/core/2.0/endpoint/token`	OAuth 2 Token	`Record` Data Type	Link to the endpoint used to obtain an access token. See Section 9, Authentication and Authorization.

Section 5, State Transitions defines other transitions that MAY be provided by the server for the Record state. Even though other transitions are not formally included in the definition of the Record state, use of other transitions is RECOMMENDED where applicable.

4.19.5 Embedded States

No embedded states are specified for the Record state.

4.19.6 Removable Components

The following components of the Record state MAY be designated by the server as removable:

rel	scope	description
`conclusion`	Each instance of `Fact` Data Type, `Gender` Data Type, and `Name` Data Type	The link used to remove the fact, gender, or name.
`evidence-reference`	Each instance of `EvidenceReference` Data Type	The link used to remove the persona (evidence) reference.
`media-reference`	Each instance of `SourceReference` Data Type	The link used to remove the media reference.
`note`	Each instance of `Note` Data Type	The link used to remove the note.
`source-reference`	Each instance of `SourceReference` Data Type	The link used to remove the source reference.

A successful DELETE request to the removable component SHOULD result in a 204 response code.

4.19.7 Example Requests

todo:

4.20 The "Relationships" State

The Relationships state consists of a list of relationships. The Relationships state is used to provide a means for a client to create a relationship or set of relationships.

4.20.1 Media Types

Applications that implement the Relationships state MUST support the application/x-gedcomx-v1+json media type as defined by the GEDCOM X JSON specification. Support for the application/x-gedcomx-v1+xml media type as defined by GEDCOM X XML is RECOMMENDED.

4.20.2 Operations

The following operations are defined as applicable to the Relationships state:

operation	description	constraints
`POST`	Create a relationship or set of relationships.	REQUIRED

If one (and only one) relationship was created as a result of a successful POST request, the request SHOULD result in a 201 response code and a Location header specifying the URI of the created relationship. If multiple relationships were created as a result of a successful POST request, the request SHOULD result in a 204 response code.

A server MAY provide other HTTP response codes as applicable under conditions established by the HTTP specification.

4.20.3 Data Elements

A list of instances of the Relationship Data Type. MUST be provided by the client in a request using the POST operation. The server considers each instance of Relationship provided by the client as a candidate to be created and added to the list of relationships.

4.20.4 Transitions

No embedded states are specified for the Relationships state.

4.20.5 Embedded States

No embedded states are specified for the Relationships state.

4.20.6 Removable Components

No removable components are specified for the Relationships state.

4.20.7 Example Requests

todo:

4.21 The "Relationship" State

The Relationship application state consists of a single relationship.

4.21.1 Media Types

Applications that implement the Relationship state MUST support the application/x-gedcomx-v1+json media type as defined by the GEDCOM X JSON specification. Support for the application/x-gedcomx-v1+xml media type as defined by GEDCOM X XML is RECOMMENDED.

4.21.2 Operations

The following operations are defined as applicable to the Relationship state:

operation	description	constraints
`GET`	Read a relationship.	REQUIRED
`POST`	Update a relationship.	OPTIONAL
`DELETE`	Delete a relationship.	OPTIONAL

A successful GET request SHOULD result in a 200 response code.

A successful POST request SHOULD result in a 204 response code. See Section 8 (Updating Application States) for more information about updating application states.

A successful DELETE request SHOULD result in a 204 response code.

A server MAY provide other HTTP response codes as applicable under conditions established by the HTTP specification.

4.21.3 Data Elements

At least one instance of the Relationship Data Type MUST be provided by the server in the successful response of a GET operation. If more than one instance of Relationship is provided, the instance that represents the "main" relationship MUST be provided as the first element in the list.

At least one instance of the Relationship Data Type MUST be provided by the client in a request using the POST operation. If more than one instance of Relationship is provided, the instance that represents the "main" relationship MUST be provided as the first element in the list.

4.21.4 Transitions

rel	target state	scope	description
`relationship`	`Relationship` State	`Relationship` Data Type	Self-link to the `Relationship` state.
`collection`	`Collection` State	`Relationship` Data Type	Link to the collection that contains this relationship.

Section 5, State Transitions defines other transitions that MAY be provided by the server for the Relationship state. Even though other transitions are not formally included in the definition of the Relationship state, use of other transitions is RECOMMENDED where applicable.

4.21.5 Embedded States

The following embedded states are specified for the Relationship state.

rel	scope	description
`evidence-references`	`Relationship` Data Type	List of evidence references for the relationship. If no link to `evidence-references` is provided, the list of evidence references MUST be included in the original request for the `Relationship` state. If a link to `evidence-references` is provided, this link SHOULD be used to create new evidence references or update existing evidence references with a `POST` request.
`media-references`	`Relationship` Data Type	List of media references for the relationship. If no link to `media-references` is provided, the list of media references MUST be included in the original request for the `Relationship` state. If a link to `media-references` is provided, this link SHOULD be used to create new media references or update existing media references with a `POST` request.
`notes`	`Relationship` Data Type	List of notes for the relationship. If no link to `notes` is provided, the list of notes MUST be included in the original request for the `Relationship` state. If a link to `notes` is provided, this link SHOULD be used to create new notes or update existing notes with a `POST` request.
`source-references`	`Relationship` Data Type	List of source references for the relationship. If no link to `source-references` is provided, the list of source references MUST be included in the original request for the `Relationship` state. If a link to `source-references` is provided, this link SHOULD be used to create new source references or update existing source references with a `POST` request.

4.21.6 Removable Components

The following components of the Relationship state MAY be designated by the server as removable:

rel	scope	description
`conclusion`	Each instance of `Fact` Data Type, `Gender` Data Type, and `Name` Data Type	The link used to remove the fact, gender, or name.
`evidence-reference`	Each instance of `EvidenceReference` Data Type	The link used to remove the relationshipa (evidence) reference.
`media-reference`	Each instance of `SourceReference` Data Type	The link used to remove the media reference.
`note`	Each instance of `Note` Data Type	The link used to remove the note.
`source-reference`	Each instance of `SourceReference` Data Type	The link used to remove the source reference.

A successful DELETE request to the removable component SHOULD result in a 204 response code.

4.21.7 Example Requests

todo:

4.22 The "Source Descriptions" State

The Source Descriptions state consists of a list of source descriptions. Examples of usages of the Source Descriptions state include to list all the descriptions of sources in a system or to provide a means for a client to create source description in a system.

4.22.1 Media Types

Applications that implement the Source Descriptions state MUST support the application/x-gedcomx-v1+json media type as defined by the GEDCOM X JSON specification. Support for the application/x-gedcomx-v1+xml media type as defined by GEDCOM X XML is RECOMMENDED.

4.22.2 Operations

The following operations are defined as applicable to the Source Descriptions state:

operation	description	constraints
`GET`	Read a list of source descriptions.	OPTIONAL
`POST`	Create an event or set of source descriptions.	OPTIONAL

A successful GET request SHOULD result in a 200 response code, if the list contains one or more source descriptions. If the list is empty, a successful GET SHOULD result in a 204 response code.

If one (and only one) event was created as a result of a successful POST request, the request SHOULD result in a 201 response code and a Location header specifying the URI of the created source description. If multiple source descriptions were created as a result of a successful POST request, the request SHOULD result in a 204 response code.

A server MAY provide other HTTP response codes as applicable under conditions established by the HTTP specification.

4.22.3 Data Elements

A list of instances of the SourceDescription Data Type. MUST be provided by the server in the successful response of a GET operation. If the list of source descriptions is large, the server MAY break up the list into multiple pages according to Section 7, Paged Application States.

A list of instances of the SourceDescription Data Type. MUST be provided by the client in a request using the POST operation. The server considers each instance of SourceDescription provided by the client as a candidate to be created and added to the list of source descriptions.

4.22.4 Transitions

The following state transitions are specified for the Source Descriptions state:

rel	target state	scope	description
`description`	`Source Description` State	Each instance of `Source Description` Data Type	Transition from the list of sources descriptions to a single source description.

Section 5, State Transitions defines other transitions that MAY be provided by the server for the Source Descriptions state. Even though other transitions are not formally included in the definition of the Source Descriptions state, use of other transitions is RECOMMENDED where applicable.

4.22.5 Embedded States

No embedded states are specified for the Source Descriptions state.

4.22.6 Removable Components

No removable components are specified for the Source Descriptions state.

4.22.7 Example Requests

todo:

4.23 The "Source Description" State

The Source Description application state consists of a single description of a source.

4.23.1 Media Types

Applications that implement the Source Description state MUST support the application/x-gedcomx-v1+json media type as defined by the GEDCOM X JSON specification. Support for the application/x-gedcomx-v1+xml media type as defined by GEDCOM X XML is RECOMMENDED.

4.23.2 Operations

The following operations are defined as applicable to the Source Description state:

operation	description	constraints
`GET`	Read a source description.	REQUIRED
`POST`	Update a source description.	OPTIONAL
`DELETE`	Delete a source description.	OPTIONAL

A successful GET request SHOULD result in a 200 response code.

A successful POST request SHOULD result in a 204 response code. See Section 8 (Updating Application States) for more information about updating application states.

A successful DELETE request SHOULD result in a 204 response code.

A server MAY provide other HTTP response codes as applicable under conditions established by the HTTP specification.

4.23.3 Data Elements

At least one instance of the SourceDescription Data Type MUST be provided by the server in the successful response of a GET operation. If more than one instance of SourceDescription is provided, the instance that represents the "main" source description MUST be provided as the first element in the list.

At least one instance of the SourceDescription Data Type MUST be provided by the client in a request using the POST operation. If more than one instance of SourceDescription is provided, the instance that represents the "main" source description MUST be provided as the first element in the list.

4.23.4 Transitions

rel	target state	scope	description
`description`	`Source Description` State	Each instance of `Source Description` Data Type	Self-link to the source description.

4.23.5 Embedded States

No embedded states are specified for the Source Description state.

4.23.6 Removable Components

No removable components are specified for the Source Description state.

4.23.7 Example Requests

todo:

5. State Transitions

This section provides a formal definition for a set of state transitions available in a genealogical data application.

5.1 Web Linking

Web links defined by RFC 5988, Web Linking are used to provide controls for declaring available transitions from application state to other application states. When a Web link resolves to a range of URIs, RFC 6570, URI Templates is used to provide a URI template to the range of URIs.

5.2 Link Relation Types

In addition to the link relation types defined by RFC 5988, the following link relation types are defined:

rel	target state	description
`agent`	`Agent` State	Link to an agent.
`ancestry`	`Ancestry Results` State	Link to the ancestry query for a person.
`artifacts`	`Artifacts` State	Link to a list of artifacts, described as sources.
`children`	`Person Children` State	Link to a list of children for a person.
`child-relationships`	`Person Children` State	Embedded link to a list of relationships to children for a person.
`collection`	`Collection` State	Link to a collection.
`subcollections`	`Collections` State	Link to a list of subcollections of a collection.
`conclusion`	(undefined)	Link to a conclusion that can be removed.
`conclusions`	`Person` State or `Relationship` State	Embedded link to a list of conclusions (names, gender, facts) of a person or to the facts of a relationship.
`current-user-person`	`Person` State	Link to the person for the current user.
`current-user-resources`	`Source Descriptions` State	Link to a list of resources that are owned by or otherwise associated with the current user, described as sources.
`descendancy`	`Descendancy Results` State	Link to the descendancy query for a person.
`description`	`Source Description` State	Link to a source description.
`description`	`Source Description` State or `Place Description` State	Link to a source description or to a place description.
`evidence-reference`	(undefined)	Link to an evidence reference that can be removed.
`evidence-references`	`Person` State or `Relationship` State	Embedded link to a list of evidence references of a person or relationship.
`http://oauth.net/core/2.0/endpoint/authorize`	user authorization page	Link to an authorization page as defined by RFC 6749, OAuth 2.
`http://oauth.net/core/2.0/endpoint/token`	access token	Link to an access token endpoint as defined by RFC 6749, OAuth 2.
`media-reference`	(undefined)	Link to a media reference that can be removed.
`media-references`	`Person` State or `Relationship` State	Embedded link to a list of media references of a person or relationship.
`note`	(undefined)	Link to a note that can be removed.
`notes`	`Person` State or `Relationship` State	Embedded link to a list of notes of a person or relationship.
`parent-relationships`	`Person` State	Embedded link to a list of relationships to parents for a person.
`parents`	`Person Parents` State	Link to a list of parents for a person.
`person`	`Person` State	Link to a person.
`persons`	`Persons` State	Link to a set of persons.
`person-search`	`Person Search` State	Templated link to a range of URIs available to use to search for a person.
`place-search`	`Place Search` State	Templated link to a range of URIs available to use to search for a place.
`record`	`Record` State	Link to a record.
`records`	`Records` State	Link to a set of records.
`relationship`	`Relationship` State	Link to a relationship.
`relationships`	`Relationships` State	Link to a set of relationships.
`source-descriptions`	`Source Descriptions` State	Link to a set of source descriptions.
`source-reference`	(undefined)	Link to a source reference that can be removed.
`source-references`	`Person` State or `Relationship` State	Embedded link to a list of source references of a person or relationship.
`spouse-relationships`	`Person` State	Embedded link to a list of relationships to spouses for a person.
`spouses`	`Person Spouses` State	Link to a list of spouses for a person.

Note that RFC 5988 declares link relation types to be Uniform Resource Identifiers. In conformance to that specification, all link relation types are declared to be relative to the http://gedcomx.org/links/ base URI. As such, the use of these link relations in an application state that is defined outside the scope of this specification SHOULD use the absolute URI, e.g. http://gedcomx.org/links/person.

5.3 URI Template Variables

Some links designate transitions to a range of application states according to RFC 6570, URI Templates.

GEDCOM X RS specifies the following template variables.

"access_token"

The "access_token" template variable is used to hold a value for an access token as defined by RFC 6749 (OAuth 2).

"count"

The "count" template variable is used to hold a count of elements in a page. For more information about paging, see Section 7.

"generations"

The "generations" template variable is used to hold a number of generations for the Ancestry Results State and the Descendancy Results State.

"start"

The "start" template variable is used to hold the index of the first element of a page of results. For more information about paging, see Section 7.

"q"

The "q" template variable is used to hold a GEDCOM X search query string.

A search query string is composed of name-value pairs. A name and value is separated by a colon ':' and each name-value pair is separated by a white space ' '.

For example:

givenName:John surname:Smith gender:male birthDate:"30 June 1900"

Notice the white space in the birthDate value. If white space is needed in the value then the value must be wrapped in double quotes. By default, values are exact. For non-exact matches append a tilde '~' at the end of the value such as:

givenName:Bob~

The following search parameters are specified:

name	description
name:	The full name of the person being searched.
givenName:	The given name of the person being searched.
surname:	The family name of the person being searched.
gender:	The gender of the person being searched. Valid values are "`male`" and "`female`".
birthDate:	The birth date of the person being searched.
birthPlace:	The birth place of the person being searched.
deathDate:	The death date of the person being searched.
deathPlace:	The death place of the person being searched.
marriageDate:	The marriage date of the person being searched.
marriagePlace:	The marriage place of the person being searched.
Relation Search Parameters The following set of standard parameters is defined as the substitution of `{relation}` with all of the values "`father`", "`mother`", "`spouse`", and "`parent`".
{relation}Name:	The full name of the {relation} of the person being searched.
{relation}GivenName:	The given name of the {relation} of the person being searched.
{relation}Surname:	The family name of the {relation} of the person being searched.
{relation}BirthDate:	The birth date of the {relation} of the person being searched.
{relation}BirthPlace:	The birth place of the {relation} of the person being searched.
{relation}DeathDate:	The death date of the {relation} of the person being searched.
{relation}DeathPlace:	The death place of the {relation} of the person being searched.
{relation}MarriageDate:	The marriage date of the {relation} of the person being searched.
{relation}MarriagePlace:	The marriage place of the {relation} of the person being searched.

6. Embedding Application States

When a client captures an application state that declares an embedded state, the client application designates the current application state as only partially captured. In order to obtain the full application state, the client must issue requests for each embedded application state, and embed the resulting data elements into the data elements of the current application state.

6.1 Embedding GEDCOM X Data Elements

Data elements that are represented using either GEDCOM X JSON or GEDCOM X XML may embed other GEDCOM X data elements as follows:

For each data element in the embedded request:
- If the element has no value for the id property, add the element to its associated list in the source data set.
- Otherwise find the element by the same id in the source data set.
  - If the element by the same id exists and is of the same data type, embed each property of the embedded data element into the source data element.
  - Otherwise, add the element to its associated list in the source data set.

7. Paged Application States

When an application state provides a large list of elements, the server MAY choose to break up the data set into smaller "pages" of data. This is done using the following state transitions, which are defined by RFC 5988:

rel	description
`first`	Link to the first page in the list.
`next`	Link to the next page in the list.
`prev`	Link to the previous page in the list.
`last`	Link to the last page in the list.

8. Updating Application States

If a server chooses to allow a client to update an application state, a client issues a POST request that contains the data elements to be updated. Each data element that does not provide a value for the id property is considered by the server as a candidate to be created. Each data element that supplies a value for the id property is considered by the server as a candidate to be updated. If the client provides an invalid value or otherwise violates a business rule of the server, a 400 response code is RECOMMENDED. A server MAY choose to provide an HTTP Warning header with text that explains the nature of the error.

9. Authentication and Authorization

A server MAY require authorization to access certain application states. Authentication and authorization are outside the scope of this specification. OAuth 2 as specified by RFC 6749 is RECOMMENDED as an authentication mechanism.

Files

rs-specification.md

Latest commit

History

rs-specification.md

File metadata and controls

GEDCOM X RS

Status

Copyright Notice

License

1. Introduction

Table Of Contents

1.1 Identifier, Version, and Dependencies

1.2 Notational Conventions

1.2.1 Keywords

1.2.2 Compliance

1.3 Concepts and Definitions

1.3.1 Client

1.3.2 Server

1.3.3 Application States

1.3.4 State Transitions (i.e. "Links")

1.3.5 Operations

1.3.6 Media Types

1.3.7 Application Entry Points

1.4 Use of HTTP

1.4.1 The Request

1.4.2 The Response

1.4.3 Content Negotiation

1.4.4 The OPTIONS Operation

example

request

response

2. Data Type Extensions

2.1 The "Link" Data Type

identifier

properties

2.1.1 The "Link" XML Type and Element

properties

examples

2.1.2 The "Link" JSON Type

properties

examples

2.1.3 The "Links" JSON Type and Member

examples

2.2 The "DisplayProperties" Data Type

identifier

properties

2.2.1 The "DisplayProperties" XML Element

properties

examples

2.2.2 The "DisplayProperties" JSON Element

properties

examples

2.3 The "FamilyView" Data Type

identifier

properties

2.3.1 The "FamilyView" XML Element

properties

examples

2.3.2 The "FamilyView" JSON Element

properties

examples

2.4 Identifier Types

2.5 The "PlaceDisplayProperties" Data Type

identifier

properties

2.5.1 The "PlaceDisplayProperties" XML Element

properties

examples

2.2.2 The "PlaceDisplayProperties" JSON Element

properties

examples

3. Property Extensions

3.1 Extensions to the "Date" Data Type

3.1.1 "Date" XML Type Extensions

3.1.2 "Date" JSON Type Extensions

3.2 Extensions to the "PlaceReference" Data Type

3.2.1 "PlaceReference" XML Type Extensions

3.2.2 "PlaceReference" JSON Type Extensions

3.3 Extensions to the "Name" Data Type