This page documents the organization of YAML documents delivered at the URIs of the standard tags in the FamilySearch GEDCOM 7 specification and the extension tag registry. The YAML documents are not part of the standard itself, and while the intent is that they remain stable and usable in the long term, if a valid reason arises they may be changed independently of the versioning process.

YAML documents in this form are used to define

  • Structure types
  • Enumeration values and sets
  • Calendars and months
  • Payload datatypes
  • Known payloads for URI-valued structures

For ease of presentation, we call whatever a YAML document is describing a “concept”.

Readable YAML

The files are provided in YAML 1.2. YAML was chosen because it is readily parseable in many programming languages and it can be formatted in a human-readable way. Because YAML provides many formatting options, using a readable style is an option, not a guarantee, and should be considered when preparing the YAML documents.

The YAML should use only untagged nodes with types seq, map, and str from the fail safe schema and null from the JSON schema.

Long strings should be wrapped on whitespace to keep the YAML under 80 columns if feasible. Strings containing newlines should be presented using the literal block style. Strings without newlines may presented in any flow style (though note the restrictions on plain style strings).

Sequences and mappings should be in the block style unless they are empty, in which case a flow style should be used instead. The top-level mapping should have a blank line between each mapping entry.

To ease machine identification of YAML blocks, document markers are recommended. In particular, documents should begin with both the YAML directive “%YAML 1.2” and the directives end marker “---”, and should end with the document end marker “...”.

YAML document schema

Each YAML document is a map with str keys.

The following shorthand types are used in this document:

Name YAML type Other constraints
Cardinality Marker str A cardinality marker as defined in the FamilySearch GEDCOM 7 specification
extTag str Matching extTag from the FamilySearch GEDCOM 7 specification
Language Tag str A valid language tag, as defined in BCP 47
stdTag str Matching stdTag from the FamilySearch GEDCOM 7 specification
Tag str Matching Tag from the FamilySearch GEDCOM 7 specification
URI str A valid URI, as defined by RFC 3986

Required keys

Three keys are always present:

  • Keylang
    TypeLanguage Tag
    Required byall
    Allowed by—

    A language tag, as specified in BCP 47. The entire YAML document is presented in this language.

  • Keytype
    Typestr from a limited set (see below)
    Required byall
    Allowed by—

    One of the following string values:

    • structure
    • enumeration
    • enumeration set
    • calendar
    • month
    • data type
    • uri

    Which other keys are present depends on the type.

    It is anticipated that additional types will be added in the future. Types for assisting in knowing which extensions a given application supports and for finding a translation of the YAML document into other languages are expected.

  • Keyuri
    TypeURI
    Required byall
    Allowed by—

    The URI that identifies the concept documented in this YAML file. If the YAML file also includes the key fragment, this URI should be followed by a fragment identifier when used; the meaning of the fragment is defined by the fragment entry.

    For example, if uri is “https://gedcom.io/terms/v7/RIN” and fragment is “Source System”, then a full URI might be “https://gedcom.io/terms/v7/RIN#MyProgram” where the fragment identifier “MyProgram” indicates the source system that generated the RIN payload value.

    Other keys

The following keys may appear in a YAML file. Their names may be changed a YAML file with a lang other than en.

  • Keycalendars
    Typeseq of URI
    Required bytype: month
    Allowed by—

    A list (in no particular order) of the URIs of calendars that use this month.

    The list may be incomplete, as a new calendar might be defined that uses an existing month.

  • Keychange controller
    Typestr
    Required by—
    Allowed byall

    An identifier of who is allowed to authorize changes to this file. For example, it could be FamilySearch, another company name, or a domain name. If not present, the change controller is the GEDCOM Steering Committee.

  • Keycontact
    Typestr
    Required by—
    Allowed byall

    Contact information for the maintainer of this file. For example, it could be personal contact information or a mailing list.

  • Keydocumentation
    Typeseq of URI
    Required by—
    Allowed byall

    One or more external URLs where additional documentation can be found. If there is no such URL, this entry should be omitted.

  • Keyenumeration set
    TypeURI
    Required bytype: structure with payload either g7:type-Enum or g7:type-List#Enum
    Allowed by—

    The URI of the set of enumeration values permitted in the payload of this structure.

  • Keyenumeration values
    Typeseq of URI
    Required bytype: enumeration set
    Allowed by—

    A list (in no particular order) of URIs of enumeration values supported by the structure.

    The listed URIs needn’t identify only enumeration values: some structures explicitly enumerate other concepts, such as https://gedcom.io/terms/v7/SOUR-EVEN enumerating even types.

    The list may be incomplete, as a new enumeration values might be defined that may be included in existing structures.

  • Keyepochs
    Typeseq of Tag
    Required bytype: calendar
    Allowed by—

    A list of all of the epoch markers used in the given calendar.

    The list should be taken as exhaustive. Extensions may not add new epochs to existing calendars.

  • Keyextension tags
    Typeseq of extTag
    Required by*
    Allowed bytypes calendar, enumeration, month, structure

    * Required instead of allowed if no standard tag is provided

    A list, with the most-preferred tag first, of extension tags known to be used by applications for this concept.

    Standard structures may have an extension tags entry to list fully compatible extensions that predated the standard and can be converted to the standard tag without any other modification. For example, 7.0’s UID structure is fully compatible with the common 5.5.1 extension identified by tag _UID.

  • Keyfragment
    Typestr
    Required by—
    Allowed bytype: uri

A recommended brief name or label for a fragment identifier, to show to users. Labels are user-centric; for programmer-centric explanations of the concept, see specification.

Labels are short to fit in forms and other constrained-space UI elements; for more detailed text see help text.

By being present in the YAML file, this field also implies that the URI should have a fragment identifier appended to it when used.
  • Keyhelp text
    Typestr
    Required by—
    Allowed byall

    A recommended detailed description to show to users. For programmer-centric explanations of the concept, see specification.

    Help text may be lengthy; for brief text to use in UI elements, see label.

  • Keylabel
    Typestr
    Required by—
    Allowed byall

    A recommended brief name or label to show to users. Labels are user-centric; for programmer-centric explanations of the concept, see specification.

    Labels are short to fit in forms and other constrained-space UI elements; for more detailed text see help text.

  • Keymonths
    Typeseq of URI
    Required bytype: calendar
    Allowed by—

    A list of all of the months used in the given calendar. Months are listed in the order they appear in a year to facilitate chronological sorting. Some calendars include leap months, so it may be that not all months appear every year in the given calendar.

    The list should be taken as exhaustive. Extensions may not add new months to existing calendars.

  • Keypayload
    Typenull or str; see below for more
    Required bytype: structure
    Allowed by—

    Indicates the payload type of the given structure. This will be one of

    • null, meaning no payload is permitted
    • The special string “Y|<NULL>”, meaning the payload is either “Y” or omitted
    • The URI of a datatype, meaning a payload of this type is required
    • A string of the form @<URI>@, meaning the payload is a pointer to a structure whose type is given by the URI.
  • Keyspecification
    Typeseq of str
    Required byall except type: enumeration set
    Allowed byall

    A list (in no particular order) of descriptions of the concept the YAML document is defining.

    The specification are generally programmer-centric; for user-centric text, see label and help text

  • Keystandard tag
    TypestdTag
    Required by*
    Allowed bytypes calendar, enumeration, month, structure

    * Required instead of allowed if no extension tag is provided

    The standard tag of this concept, as given in an official GEDCOM standard document.

  • Keysubsumes
    Typeseq of URI
    Required by—
    Allowed byall

    A list of URIs that can be replaced by this URI without any loss of information or change of meaning. This does not simply mean they can express the same thing, but rather that they express the same thing in the same way, i.e., with no change in payloads or substructures.

    One example use-case is an extension becoming standard and being given a URI with a gedcom.io host, in which case both the extension URI’s YAML file and the standard URI’s YAML file can list the other as URIs it subsumes.

    Another example use-case is an extension that adds to another extension, for example by allowing a larger set of payloads or more substructures. In this case the more permissive/larger extension would say it subsumes the more strict/smaller extension, but not the other way around.

  • Keysubstructures and superstructures
    Typemap with URI keys and Cardinality Marker values
    Required bytype: structure
    Allowed by—

    These express how structures may be nested, and with what cardinality. Structure types are given by URI; cardinalities are expressed using the same strings as the standard (i.e. “{0:1}”, “{1:1}”, “{0:M}”, and “{1:M}”)

    Because new structures may be added over time in any order, x may be a substructure of y if either x’s superstructures includes y or y’s substructures includes x.

    If the relationship is listed in both a substructures entry and a superstructures entry, the two must have the same cardinality.

    If superstructures is an empty map, then the structure is a record and must not appear in any other structure’s substructures.

  • Keyused by
    Typeseq of str
    Required by—
    Allowed byall

    A list of g7:HEAD-SOUR values of applications known to use an extension tag for this concept.

  • Keyvalue of
    Typeseq of URI
    Required bytype: enumeration
    Allowed bytype: structure*

    * Note that potentially any concept could be referred to in an enumeration set, and hence any YAML file could include the value of key. So far, all known examples are either type: enumeration or type: structure.

    A list (in no particular order) of enumeration sets that are known to contain this concepts as an enumeration value.

    The list may be incomplete, as a new enumeration set might be defined that re-uses an existing enumeration value.