Permalink
1368 lines (1031 sloc) 48 KB

The GEDCOM X JSON Serialization Format

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

Copyright Intellectual Reserve, Inc.

License

This document is distributed under a Creative Commons Attribution-ShareAlike license. For details, see:

http://creativecommons.org/licenses/by-sa/3.0/

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.

Table Of Contents

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 gender of the person. gender Gender
names The names of the person. names array of Name
facts The facts of the person. facts array of Fact

examples

{

  //...the members of [Subject](#subject)/*...*/,

  "private" : false,
  "gender" : { /*...*/ },
  "names" : [ { /*...*/ }, { /*...*/ } ],
  "facts" : [ { /*...*/ }, { /*...*/ } ]
}

2.2 The "Relationship" Data Type

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

properties

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

examples

{

  //...the members of [Subject](#subject)/*...*/,

  "type" : "http://gedcomx.org/Couple",
  "person1" : {
    "resource" : "http://identifier/for/person/1"
  },
  "person2" : {
    "resource" : "http://identifier/for/person/2"
  },
  "facts" : [ { /*...*/ }, { /*...*/ } ]
}

2.3 The "SourceDescription" Data Type

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

properties

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
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)
repository A reference to the repository that contains the described resource. repository ResourceReference

examples

{
  "id" : "local_id",
  "resourceType" : "...",
  "citations" : [ { /*...*/ }, { /*...*/ } ],
  "mediaType" : "...",
  "about" : "http://identifier/for/the/source/being/described",
  "mediator" : {
    "resource" : "http://identifier/for/the/mediator/of/source/being/described"
  },
  "sources" : [ { /*...*/ }, { /*...*/ } ],
  "analysis" : {
    "resource" : "http://identifier/for/analysis/document"
  },
  "componentOf" : { /*...*/ },
  "titles" : [ { /*...*/ }, { /*...*/ } ],
  "notes" : [ { /*...*/ }, { /*...*/ } ],
  "attribution" : { /*...*/ },
  "rights" : [ { /*...*/ }, { /*...*/ }],
  "coverage" : { /*...*/ },
  "descriptions" : [ { /*...*/ }, { /*...*/ } ],
  "identifiers" : { /*...*/ }
  "created" : /*...*/,
  "modified" : /*...*/,
  "repository" : { /*...*/ }

  //...possibility of extension elements...

}

2.4 The "Agent" Data Type

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

properties

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

examples

{
  "id" : "local_id",
  "identifiers" : { /*...*/ }
  "names" : [ { /*...*/ }, { /*...*/ } ],
  "homepage" : {
    "resource" : "..."
  },
  "openid" : {
    "resource" : "..."
  },
  "accounts" : [ { /*...*/ }, { /*...*/ } ],
  "emails" : [ { "resource" : "mailto:someone@gedcomx.org" } , { "resource" : "mailto:someone@somewhere-else.org" } ],
  "phones" : [ { "resource" : "tel:+1-201-555-0123" } , { "resource" : "fax:+1-201-555-5555" } ],
  "addresses" : [ { /*...*/ }, { /*...*/ } ],
  "person" : { "resource" : "..." }

  //...possibility of extension elements...

}

2.5 The "Event" Data Type

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

properties

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

examples

{

  //...the members of [Subject](#subject)...,

  "type" : "http://gedcomx.org/Marriage",
  "date" : { /*...*/ },
  "place" : { /*...*/ },
  "roles" : [ { /*...*/ }, { /*...*/ } ]
}

2.6 The "Document" Data Type

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

properties

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

examples

{

  //...the members of [Conclusion](#conclusion)...,

  "extracted" : false,
  "type" : "http://gedcomx.org/Analysis",
  "attribution" : { /*...*/ },
  "textType" : "plain",
  "text" : "...text of the document..."
}

2.7 The "PlaceDescription" Data Type

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

properties

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

examples

{

  //...the members of [Subject](#subject)...,

  "names" : [ {
    "lang" : "en",
    "value" : "Pope's Creek, Westmoreland, Virginia, United States"
  } ,
  {
    "lang" : "zh",
    "value" : "教皇的小河,威斯特摩兰,弗吉尼亚州,美国"
  } ],
  "type" : "http://identifier/for/the/place/type",
  "place" : { "resource" : "..." },
  "jurisdiction" : { "resource" : "..." },
  "latitude" : "27.9883575",
  "latitude" : "86.9252014",
  "temporalDescription" : { /*...*/ },
  "spatialDescription" : {
    "resource" : "http://uri/for/KML/document"
  }
}

3. Component-Level Data Types

This section specifies JSON types for each component-level data type defined by the conceptual model specification.

3.1 The "Identifier" Data Type

In JSON, the http://gedcomx.org/v1/Identifier data type is always serialized in the context of a set of identifiers, which is represented using a JSON object. The name of each member of the object is the identifier type. The value of each member carries the string values of the identifiers of that type. All known GEDCOM X identifier types MAY carry multiple values, so the value of the member for each known identifier type MUST be an array of strings.

Some custom identifier types MAY specify that the identifier type is "single-valued", meaning there MUST NOT be more than one value of the specified identifier type, per entity. If an identifier type is specified as a "single-valued" identifier type, the value of the member named by that identifier type MAY forgo the array and use a single string.

Since the identifier type is an OPTIONAL property, the name of the member that carries untyped identifiers SHALL be "$".

example: set of identifiers

{
  "$" : [ "value_of_untyped_identifier" ],
  "http://gedcomx.org/IdentifierType" : [ "value_of_identifier" ],
  "http://gedcomx.org/OtherIdentifierType" : [ "value_of_identifier" ],
  "http://custom.org/SingleValuedIdentifierType" : "value_of_identifier",
  ...
}

3.2 The "Attribution" Data Type

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

properties

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)

examples

{
  "contributor" : {
    "resource" : "http://identifier/for/contributor"
  },
  "modified" : 1338494969,
  "changeMessage" : "...change message here..."
  "creator" : {
    "resource" : "http://identifier/for/creator"
  },
  "created" : 1338394969,

  //...possibility of extension elements...

}

3.3 The "Note" Data Type

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

properties

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

examples

{
  "lang" : "en",
  "subject" : "...",
  "text" : "...",
  "attribution" : { /*...*/ }

  //...possibility of extension elements...

}

3.4 The "TextValue" Data Type

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

properties

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

examples

A value that can be specified as a string:

{
  "lang" : "en",
  "value" : "...text of the value..."
}

3.5 The "SourceCitation" Data Type

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

properties

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

examples

{
  "lang" : "en",
  "value" : "...a rendering of the full citation as a string..."

  //...possibility of extension elements...

}

3.6 The "SourceReference" Data Type

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

properties

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

examples

{
  "description" : "http://identifier/for/description/of/source/being/referenced",
  "descriptionId" : "...",
  "attribution" : { /*...*/ }

  //...possibility of extension elements...

}

3.7 The "EvidenceReference" Data Type

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

properties

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

examples

{
  "resource" : "http://identifier/for/data/being/referenced",
  "attribution" : { /*...*/ }

  //...possibility of extension elements...

}

3.8 The "OnlineAccount" Data Type

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

properties

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

examples

{
  "serviceHomepage" : {
    "resource" : "http://familysearch.org/"
  },
  "accountName" : "..."

  //...possibility of extension elements...

}

3.9 The "Address" Data Type

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

properties

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

examples

{
  "value" : "...",
  "city" : "...",
  "country" : "...",
  "postalCode" : "...",
  "stateOrProvince" : "...",
  "street" : "...",
  "street2" : "...",
  "street3" : "...",
  "street4" : "...",
  "street5" : "...",
  "street6" : "..."

  //...possibility of extension elements...

}

3.10 The "Conclusion" Data Type

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

properties

name description JSON member JSON object type
id An identifier for the JSON object holding this conclusion's data. The id attribute MUST conform to the constraints defined in Section 7, "Fragment Identifiers". id string
lang The locale identifier for the conclusion. lang IETF BCP 47 locale tag
sources The list of references to sources related to this conclusion. sources array of SourceReference.
analysis Reference to a document containing analysis supporting this conclusion. analysis ResourceReference
notes A list of notes about this conclusion. notes array of Note
confidence Reference to a confidence level for this conclusion. confidence URI
attribution The attribution of this conclusion. attribution Attribution

examples

{
  "id" : "local_id",
  "lang" : "en",
  "sources" : [ { /*...*/ }, { /*...*/ } ],
  "analysis" : {
    "resource" : "http://identifier/for/analysis/document"
  },
  "notes" : [ { /*...*/ }, { /*...*/ } ],
  "confidence" : "http://gedcomx.org/High"
  "attribution" : { /*...*/ }

  //...possibility of extension elements...

}

3.11 The "Subject" Data Type

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

properties

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

examples

{

  //...the members of [Conclusion](#conclusion)...,

  "extracted" : false,
  "evidence" : [ { /*...*/ }, { /*...*/ } ],
  "media" : [ { /*...*/ }, { /*...*/ } ],
  "identifiers" : { /*...*/ }
}

3.12 The "Gender" Data Type

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

properties

name description JSON member JSON object type
type URI identifying the gender. type URI

examples

{

  //...the members of [Conclusion](#conclusion)...,

  "type" : "http://gedcomx.org/Male"
}

3.13 The "Name" Data Type

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

properties

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

examples

{

  ...the members of [Conclusion](#conclusion)...,

  "type" : "http://gedcomx.org/BirthName",
  "date" : { /*...*/ },
  "nameForms" : [ { /*...*/ }, { /*...*/ } ]
}

3.14 The "Fact" Data Type

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

properties

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

examples

{

  //...the members of [Conclusion](#conclusion)...,

  "type" : "http://gedcomx.org/Birth",
  "date" : { /*...*/ },
  "place" : { /*...*/ },
  "value" : "...the original value of the fact...",
  "qualifiers" : [ { "name" : "http://gedcomx.org/Age", "value" : "..." } ]
}

3.15 The "EventRole" Data Type

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

properties

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

examples

{

  //...the members of [Conclusion](#conclusion)...,

  "person" : {
    "resource" : "http://identifier/for/person/1"
  },
  "type" : "http://gedcomx.org/Witness",
  "details" : "..."
}

3.16 The "Date" Data Type

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

properties

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

examples

{
  "original" : "...the original text...",
  "formal" : "..."

  //...possibility of extension elements...

}

3.17 The "PlaceReference" Data Type

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

properties

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

examples

{
  "original" : "...the original text...",
  "description" : "http://identifier/of/place-description/being/referenced",

  //...possibility of extension elements...

}

3.18 The "NamePart" Data Type

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

properties

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

examples

{
  "type" : "http://gedcomx.org/Surname",
  "value" : "...value of the name part..."
  "qualifiers" : [ { "name" : "http://gedcomx.org/Family" }, { "name" : "http://gedcomx.org/Patronymic" } ]

  //...possibility of extension elements...

}

3.19 The "NameForm" Data Type

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

properties

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

examples

{
  "lang" : "en",
  "fullText" : "...full text of the name form...",
  "parts" : [ { /*...*/ }, { /*...*/ } ]

  //...possibility of extension elements...

}

3.20 The "Qualifier" Data Type

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

properties

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

examples

{
  "name" : "http://gedcomx.org/QualifierName",
  "value" : "..."
}

3.21 The "Coverage" Data Type

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

properties

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

examples

{
  "spatial" : { /*...*/ },
  "temporal" : { /*...*/ }
}

4 JSON-Specific Data Types

This section describes a set of data types that are specific to the GEDCOM X JSON media type, used for the convenience of serialization.

4.1 The URI

URIs are supplied as JSON strings and are interpreted according to RFC 3986: Uniform Resource Identifier (URI): Generic Syntax.

4.2 The "ResourceReference" Data Type

The ResourceReference JSON type is used for properties that reference other resources. It uses the resource member to refer to other resources.

properties

name description JSON member JSON object type
resource The URI to the resource being referenced. resource URI

examples

{
  "resource" : "http://uri/to/resource/being/referenced"
}

4.3 The "Gedcomx" Data Type

The Gedcomx JSON type is used as a container for a set of GEDCOM X data.

properties

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.
description Reference to the description of this data set. description URI OPTIONAL. If provided, MUST resolve to an instance of SourceDescription.

examples

{
  "id" : "local_id",
  "description" : "...",
  "attribution" : { /*...*/ },
  "persons" : [ { /*...*/ }, { /*...*/ } ],
  "relationships" : [ { /*...*/ }, { /*...*/ }, ],
  "sourceDescriptions" : [ { /*...*/ }, { /*...*/ } ],
  "agents" : [ { /*...*/ } , { /*...*/ } ],
  "events" : [ { /*...*/ } , { /*...*/ } ],
  "documents" : [ { /*...*/ } , { /*...*/ } ],
  "places" : [ { /*...*/ } , { /*...*/ } ],

  //...possibility of extension elements...

}

5. The GEDCOM X Object

The body of a document compliant with the GEDCOM X JSON media type MUST be an instance of the GEDCOM X Object, which is defined by an JSON object of the Gedcomx data type.

Example

The following is an example of the structure of a GEDCOM X JSON Element:

{
  "id" : "local_id",
  "attribution" : { /*...*/ },
  "persons" : [ { /*...*/ }, { /*...*/ } ],
  "relationships" : [ { /*...*/ }, { /*...*/ }, ],
  "sourceDescriptions" : [ { /*...*/ }, { /*...*/ } ],
  "agents" : [ { /*...*/ } , { /*...*/ } ],
  "events" : [ { /*...*/ } , { /*...*/ } ],
  "documents" : [ { /*...*/ } , { /*...*/ } ],
  "places" : [ { /*...*/ } , { /*...*/ } ],

  //...possibility of extension elements...

}

6. Extensibility

In accordance with the extensibility provisions of the GEDCOM X Conceptual Model, extensions MAY be provided as JSON members on data types where extensions are not explicitly prohibited.

6.1 Data Type Extensions

New data types MAY be defined as extensions to the GEDCOM X JSON Serialization Format by providing the following:

Specifications that define new data types as GEDCOM X JSON extensions MUST be published and made freely available and compatible with the terms and constraints that govern the GEDCOM X JSON Serialization Format.

6.2 Known JSON Extension Members

GEDCOM X defines a set of JSON members that are explicitly associated with a data type such that GEDCOM X JSON parsers MAY interpret the members correctly if they are included as an extension member in a valid data type as defined by the conceptual model. The following members are identified:

name JSON object type
persons array of Person
relationships array of Relationship
sourceDescriptions array of SourceDescription
agents array of Agent
events array of Event
documents array of Document
placeDescriptions array of PlaceDescription
attribution array of Attribution
notes array of Note
sourceReferences array of SourceReference
genders array of Gender
names array of Name
facts array of Fact

7. Fragment Identifiers

Fragment identifiers are used to identify specific objects (i.e. "fragments") within a JSON document. The GEDCOM X JSON serialization format specifies the use of the "id" member as the fragment identifier for any object in a given JSON document. Note that some data types explicitly define an "id" property, but the JSON serialization format allows the option of an "id" property on all objects for the purpose of identifying fragments of the JSON document. The values of all fragment identifiers within a single JSON document MUST be unique.

For more information about fragment identifiers, see RFC 3986, Section 3.5.