The GEDCOM X JSON Serialization Format

August 4, 2024 · View on GitHub

Status

This document specifies a JSON media type for the GEDCOM X Conceptual Model, and requests discussion and suggestions for improvements.

The current state of this document is as a "stable draft", and as such, the document may be subject to limited changes, BUT NOT 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/

Summary

The GEDCOM X JSON Serialization Format spec specifies how to represent the GEDCOM X Conceptual Model in JSON. The spec includes examples, notational conventions, top-level data types, component-level data types, JSON-specific data types, the GEDCOM X object, extensibility, and fragment identifiers.

1. Introduction

The GEDCOM X Conceptual Model is a specification of formal concepts and types that are used to provide a standard model and vocabulary for describing genealogical data.

The GEDCOM X JSON Serialization Format is a specification that defines the media type used to serialize and deserialize the GEDCOM X Conceptual Model to and from JSON.

1. Introduction
2. Top-Level Data Types
3. Component-Level Data Types
4. JSON-Specific Data Types
5. The GEDCOM X Object
6. Extensibility
7. Fragment Identifiers

1.1 Identifier, Version, and Dependencies

The identifier for this specification is:

http://gedcomx.org/json/v1

For convenience, the GEDCOM X JSON Format may be referred to as "GEDCOM X JSON 1.0".

The media type defined by this specification is:

application/x-gedcomx-v1+json

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

1.2 Examples

The following example shows an instance of a GEDCOM X serialization in accordance with this specification:

{
  "attribution" : {
    "contributor" : {
      "resource" : "#GGG-GGGG"
    }
  },
  "persons" : [ {
    "names" : [ {
      "nameForms" : [ {
        "fullText" : "George Washington",
        "parts" : [ {
          "value" : "George",
          "type" : "http://gedcomx.org/Given"
        }, {
          "value" : "Washington",
          "type" : "http://gedcomx.org/Surname"
        } ]
      } ],
      "id" : "789"
    } ],
    "gender" : {
      "type" : "http://gedcomx.org/Male"
    },
    "facts" : [ {
      "type" : "http://gedcomx.org/Birth",
      "date" : {
        "original" : "February 22, 1732",
        "formal" : "+1732-02-22"
      },
      "place" : {
        "original" : "pope's creek, westmoreland, virginia, united states",
        "description" : "#888"
      },
      "id" : "123"
    }, {
      "type" : "http://gedcomx.org/Death",
      "date" : {
        "original" : "December 14, 1799",
        "formal" : "+1799-12-14T22:00:00"
      },
      "place" : {
        "original" : "mount vernon, fairfax county, virginia, united states",
        "description" : "#999"
      },
      "id" : "456"
    } ],
    "sources" : [ {
      "description" : "#EEE-EEEE"
    } ],
    "id" : "BBB-BBBB"
  }, {
    "names" : [ {
      "nameForms" : [ {
        "fullText" : "Martha Dandridge Custis",
        "parts" : [ {
          "value" : "Martha Dandridge",
          "type" : "http://gedcomx.org/Given"
        }, {
          "value" : "Custis",
          "type" : "http://gedcomx.org/Surname"
        } ]
      } ],
      "id" : "987"
    } ],
    "gender" : {
      "type" : "http://gedcomx.org/Male"
    },
    "facts" : [ {
      "type" : "http://gedcomx.org/Birth",
      "date" : {
        "original" : "June 2, 1731",
        "formal" : "+1731-06-02"
      },
      "place" : {
        "original" : "chestnut grove, new kent, virginia, united states",
        "description" : "#KKK"
      },
      "id" : "321"
    }, {
      "type" : "http://gedcomx.org/Death",
      "date" : {
        "original" : "May 22, 1802",
        "formal" : "+1802-05-22"
      },
      "place" : {
        "original" : "mount vernon, fairfax county, virginia, united states",
        "description" : "#999"
      },
      "id" : "654"
    } ],
    "sources" : [ {
      "description" : "#FFF-FFFF"
    } ],
    "id" : "CCC-CCCC"
  } ],
  "relationships" : [ {
    "facts" : [ {
      "type" : "http://gedcomx.org/Marriage",
      "date" : {
        "original" : "January 6, 1759",
        "formal" : "+1759-01-06"
      },
      "place" : {
        "original" : "White House Plantation"
      }
    } ],
    "person1" : {
      "resource" : "#BBB-BBBB"
    },
    "person2" : {
      "resource" : "#CCC-CCCC"
    },
    "sources" : [ {
      "description" : "#FFF-FFFF"
    } ],
    "id" : "DDD-DDDD"
  } ],
  "sourceDescriptions" : [ {
    "citations" : [ {
      "value" : "\"George Washington.\" Wikipedia, The Free Encyclopedia. Wikimedia Foundation, Inc. 24 October 2012."
    } ],
    "about" : "http://en.wikipedia.org/wiki/George_washington",
    "id" : "EEE-EEEE"
  }, {
    "citations" : [ {
      "value" : "\"Martha Washington.\" Wikipedia, The Free Encyclopedia. Wikimedia Foundation, Inc. 24 October 2012."
    } ],
    "about" : "http://en.wikipedia.org/wiki/Martha_washington",
    "id" : "FFF-FFFF"
  } ],
  "agents" : [ {
    "names" : [ {
      "value" : "Ryan Heaton"
    } ],
    "id" : "GGG-GGGG"
  } ],
  "places" : [ {
    "names" : [ {
      "value" : "Pope's Creek, Westmoreland, Virginia, United States"
    } ],
    "latitude" : 38.192353,
    "longitude" : -76.904069,
    "id" : "888"
  }, {
    "names" : [ {
      "value" : "Mount Vernon, Fairfax County, Virginia, United States"
    } ],
    "latitude" : 38.721144,
    "longitude" : -77.109461,
    "id" : "999"
  }, {
    "names" : [ {
      "value" : "Chestnut Grove, New Kent, Virginia, United States"
    } ],
    "latitude" : 37.518304,
    "longitude" : -76.984148,
    "id" : "KKK"
  } ]
}

1.3 Notational Conventions

1.3.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.3.2 Data Types

For each data type specified by the GEDCOM X Conceptual Model, a JSON data format is supplied which specifies how each of the properties of the data type are to be serialized in JSON. Each instance of a data type is serialized as a JSON object. The properties of each data type are serialized as members of the JSON object.

1.4 Compliance

In addition to the compliance requirements provided by this specification, all compliance requirements provided by the GEDCOM X Conceptual Model identified by http://gedcomx.org/conceptual-model/v1 are inherited.

2. Top-Level Data Types

This section specifies JSON types for each top-level data type defined by the GEDCOM X Conceptual Model specification.

2.1 The "Person" Data Type

The JSON object used to (de)serialize the http://gedcomx.org/v1/Person data type is defined as follows:

properties

name	description	JSON member	JSON object type
private	Whether this instance of `Person` has been designated for limited distribution or display.	private	boolean
gender	The sex of the person as assigned at birth	gender	`Gender`
names	The names of the person.	names	array of `Name`
facts	The facts of the person.	facts	array of `Fact`

name	description	JSON member	JSON object type
type	URI identifying the type of the relationship.	type	`URI`
person1	Reference to the first person in the relationship.	person1	`ResourceReference`
person2	Reference to the second person in the relationship.	person2	`ResourceReference`
facts	The facts about the relationship.	facts	array of `Fact`

name	description	JSON member	JSON object type
id	The identifier for the JSON object holding the source description data. The id attribute MUST conform to the constraints defined in Section 7, "Fragment Identifiers".	id	string
resourceType	URI identifying the type of resource being described.	resourceType	`URI`
citations	The citation(s) for this source.	citations	array of `SourceCitation`
mediaType	A hint about the media type of the resource being described.	mediaType	string
about	A uniform resource identifier (URI) for the resource being described.	about	`URI`
mediator	A reference to the entity that mediates access to the described source.	mediator	`ResourceReference`
publisher	A reference to the entity responsible for making the described source available.	publisher	`ResourceReference`
authors	A list of references to the entities that authored the described source.	authors	array of `ResourceReference`
sources	A list of references to any sources from which this source is derived.	sources	array of `SourceReference`
analysis	A reference to a document containing analysis about this source.	analysis	`ResourceReference`
componentOf	A reference to the source that contains this source.	componentOf	`SourceReference`
titles	The display name(s) for this source.	titles	array of `TextValue`
notes	A list of notes about a source	notes	array of `Note`
attribution	The attribution of this source.	attribution	`Attribution`
rights	The rights for this resource.	rights	array of `ResourceReference`
coverage	The coverage of the resource.	coverage	array of `Coverage`
descriptions	Human-readable descriptions of this source.	descriptions	array of `TextValue`
identifiers	A list of identifiers for the resource being described.	identifiers	`Identifier`
created	Timestamp of when the resource being described was created.	created	number (milliseconds since epoch)
modified	Timestamp of when the resource being described was modified.	modified	number (milliseconds since epoch)
published	Timestamp of when the resource being described was published.	published	number (milliseconds since epoch)
repository	A reference to the repository that contains the described resource.	repository	`ResourceReference`

name	description	JSON member	JSON object type
id	An identifier for the JSON object holding the agent data. The id attribute MUST conform to the constraints defined in Section 7, "Fragment Identifiers".	id	string
identifiers	Identifiers for this agent.	identifiers	`Identifier`
names	The name(s) of the person or organization.	names	array of `TextValue`
homepage	The homepage of the person or organization.	homepage	`ResourceReference`
openid	The openid of the person or organization.	openid	`ResourceReference`
accounts	The online account(s) of the person or organization.	accounts	array of `OnlineAccount`
emails	The email address(es) of the person or organization.	emails	array of `ResourceReference`
phones	The phone(s) (voice, fax, mobile) of the person or organization.	phones	array of `ResourceReference`
addresses	The address(es) of the person or organization.	addresses	array of `Address`
person	A reference to the person that describes this agent.	person	`ResourceReference`

name	description	JSON member	JSON object type
type	URI identifying the type of the event.	type	`URI`
date	The date of the event.	date	`Date`
place	The place of the event.	place	`PlaceReference`
roles	Information about how persons participated in the event.	roles	array of `EventRole`

name	description	JSON member	JSON object type
type	URI identifying the type of the document.	type	`URI`
extracted	Whether this document is to be constrained as an extracted conclusion.	extracted	boolean
textType	The type of text in the `text` property.	textType	string
text	The text of the document.	text	string
attribution	The attribution of this document.	attribution	`Attribution`

name	description	JSON member	JSON object type
names	A list of standardized (or normalized), fully-qualified (in terms of what is known of the applicable jurisdictional hierarchy) names for this place that are applicable to this description of this place.	names	array of `TextValue`
type	A uniform resource identifier (URI) identifying the type of the place as it is applicable to this description.	type	`URI`
place	An identifier for the place being described.	place	`ResourceReference`
jurisdiction	A reference to a description of the jurisdiction of this place.	jurisdiction	`ResourceReference`
latitude	Angular distance, in degrees, north or south of the Equator.	latitude	number
longitude	Angular distance, in degrees, east or west of the Prime Meridian.	longitude	number
temporalDescription	A description of the time period to which this place description is relevant.	temporalDescription	`Date`
spatialDescription	A reference to a geospatial description of this place.	spatialDescription	`ResourceReference`

name	description	JSON member	JSON object type
names	A list of names of the group.	names	array of `TextValue`
date	The date of applicability of the group.	date	`Date`
place	The place of applicability of the group.	place	`PlaceReference`
roles	Information about how persons participated in the event.	roles	array of `EventRole`

name	description	JSON member	JSON object type
contributor	Reference to the contributor to whom the attributed data is attributed.	contributor	`ResourceReference`
modified	Timestamp of when the attributed data was contributed.	modified	number (milliseconds since epoch)
changeMessage	A statement of why the attributed data is being provided by the contributor.	changeMessage	string
creator	Reference to the agent that created the attributed data. The creator MAY be different from the contributor if changes were made to the attributed data.	creator	`ResourceReference`
created	Timestamp of when the attributed data was contributed.	created	number (milliseconds since epoch)

name	description	JSON member	JSON object type
lang	The locale identifier for the note.	lang	IETF BCP 47 locale tag
subject	A subject or title for the note.	subject	string
text	The text of the note.	text	string
attribution	The attribution of this note.	attribution	`Attribution`

name	description	JSON member	JSON object type
lang	The locale identifier for the value of the text.	lang	IETF BCP 47 locale tag
value	The text value.	value	string

name	description	JSON member	JSON object type
value	A full representation of the complete address.	value	string
city	The city.	city	string
country	The country.	country	string
postalCode	The postal code.	postalCode	string
stateOrProvince	The state or province.	stateOrProvince	string
street	The street.	street	string
street2	The street (second line).	street2	string
street3	The street (third line).	street3	string
street4	The street (fourth line).	street4	string
street5	The street (fifth line).	street5	string
street6	The street (sixth line).	street6	string

name	description	JSON member	JSON object type
lang	The locale identifier for the citation.	lang	IETF BCP 47 locale tag
value	A rendering of the full citation as a string.	value	string

name	description	JSON member	JSON object type
descriptionRef	Reference to a description of the source being referenced.	description	`URI`
descriptionId	The id of the target source.	descriptionId	string
attribution	The attribution of this source reference.	attribution	`Attribution`
qualifiers	Qualifiers for the reference, used to identify specific fragments of the source that are being referenced.	qualifiers	array of `Qualifier`

name	description	JSON member	JSON object type
resource	Reference to the supporting data.	resource	`URI`
attribution	The attribution of this evidence reference.	attribution	`Attribution`

name	description	JSON member	JSON object type
serviceHomepage	The URI identifying the online service provider that holds the account being described.	serviceHomepage	`ResourceReference`
accountName	The name, label, or id that uniquely identifies the account maintained by the online service provider.	accountName	string

name	description	JSON member	JSON object type
extracted	Whether this subject is to be constrained as an extracted conclusion.	extracted	boolean
evidence	References to other subjects that support this subject.	evidence	array of `EvidenceReference`
media	References to multimedia resources for this subject, such as photos or videos.	media	array of `SourceReference`
identifiers	Identifiers for this subject.	identifiers	`Identifier`

name	description	JSON member	JSON object type
type	URI identifying the name type.	type	`URI`
date	The date of applicability of the name.	date	`Date`
nameForms	The name form(s) that best represents this name; representations of the same name—*not* name variants (i.e., not nicknames or spelling variations).	nameForms	array of `NameForm`

name	description	JSON member	JSON object type
type	URI identifying the type of the fact.	type	`URI`
date	The date of applicability of the fact.	date	`Date`
place	The place of applicability of the fact.	place	`PlaceReference`
value	The value of the fact.	value	string
qualifiers	Qualifiers to add additional details about the fact.	qualifiers	array of `Qualifier`

name	description	JSON member	JSON object type
person	Reference to the event participant.	person	`ResourceReference`
type	URI identifying the participant's role.	type	`URI`
details	Details about the role of participant in the event.	details	string

name	description	JSON member	JSON object type
original	The original value of the date as supplied by the contributor.	original	string
formal	The standardized, formal representation of the date.	formal	GEDCOM X Date

name	description	JSON member	JSON object type
original	The original place name text as supplied by the contributor.	original	string.
descriptionRef	A reference to a description of this place.	description	`URI`

name	description	JSON member	JSON object type
type	URI identifying the type of the name part.	type	`URI`
value	The term(s) from the name that make up this name part.	value	string
qualifiers	Qualifiers to add additional semantic meaning to the name part.	qualifiers	array of `Qualifier`

name	description	JSON member	JSON object type
lang	The locale identifier for the name form.	lang	IETF BCP 47 locale tag
fullText	A full rendering of the name.	fullText	string
parts	Any identified name parts from the name.	parts	array of `NamePart`

name	description	JSON member	JSON object type
name	The name of the qualifier.	name	`URI`
value	The value of the qualifier.	value	string

name	description	JSON member	JSON object type
spatial	The spatial (i.e., geographic) coverage.	spatial	`PlaceReference`
temporal	The temporal coverage.	temporal	`Date`

name	description	JSON member	JSON object type
person	Reference to the group participant.	person	`ResourceReference`
type	URI identifying the participant's role.	type	`URI`
date	The date of applicability of the role.	date	`Date`
details	Details about the role of participant in the group.	details	string

name	description	JSON member	JSON object type	constraints
id	An identifier for the data set.	id	string	OPTIONAL. If provided, the `id` attribute MUST conform to the constraints defined in Section 7, "Fragment Identifiers".
lang	The locale identifier for the data set.	lang	IETF BCP 47 locale tag	OPTIONAL. If not provided, the locale is determined per Internationalization Considerations.
attribution	The attribution of this data set.	attribution	`Attribution`	OPTIONAL.
persons	The list of persons contained in the data set.	persons	array of `Person`	OPTIONAL.
relationships	The list of relationships contained in the data set.	relationships	array of `Relationship`	OPTIONAL.
sourceDescriptions	The list of source descriptions contained in the data set.	sourceDescriptions	array of `SourceDescription`	OPTIONAL.
agents	The list of agents contained in the data set.	agents	array of `Agent`	OPTIONAL.
events	The list of events contained in the data set.	events	array of `Event`	OPTIONAL.
documents	The list of documents contained in the data set.	documents	array of `Document`	OPTIONAL.
places	The list of places contained in the data set.	places	array of `PlaceDescription`	OPTIONAL.
groups	The list of groups contained in the data set.	groups	array of `Group`	OPTIONAL.
description	Reference to the description of this data set.	description	`URI`	OPTIONAL. If provided, MUST resolve to an instance of `SourceDescription`.