Chapter 1 - Data Representation Grammar

The generic data representation language defined in this chapter may be used to represent any form of structured information, not just genealogical data, using a sequential stream of characters.

Concepts

In addition to hierarchical relationships, GEDCOM defines inter-record relationships which allow a record to be logically related to other records, without introducing redundancy. These relationships are represented by two additional but optional parts of a line: a cross-reference pointer and a cross-reference identifier. The cross-reference pointer "points at" a related record, identified by a required, matching unique cross-reference identifier. The cross-reference identifier is analogous to a primary key in relational database terminology.

Grammar

• The beginning of a new physical record is designated by a line whose level number is 0.
• Physical records are intended to be small enough to fit within a memory buffer of typical size, though absolute limits are not established.
• The total length of a GEDCOM-line, including leading white space and terminators, does not exceed 255 characters. Long text can be represented by using CONTinue or CONCatenate tags.
• Leading white space (tabs, spaces, and extra line terminators) preceding a GEDCOM-line should be ignored by the reading system. Systems generating GEDCOM should not place any white space in front of the GEDCOM-line (at least for the near future, see Compatibility With Previous GEDCOM Versions at the end of chapter 2).
• Level numbers must not contain leading zeroes which are not significant, for example, level one must be 1, not 01.
• GEDCOM-lines constructed with user defined tags must include a tag definition in the a schema substructure in the transmission header record. The user defined tag must begin with an underscore (_). The schema allows a receiving system to interpret the associated data. (See the User Defined Tags section in chapter 2 for more information).

alpha:=

The alpha characters include the underscore which is used to link word pieces together in forming tag names or tag labels.

any_char:=

Any character except the control characters found in the range of 0x00 - 0x1F. If an @ is desired as part of the line_value, it must be written in GEDCOM as a double @, ie., "3 doz. @ $20.00" must be stored as "3 doz. @@ $20.00".

delim:=

The delim (delimiter), a single space character, terminates both the variable-length level number and the variable-length tag. Note that space characters may also be present in a value.

escape:=

The escape is a sequence in the grammar used to specify special processing, such as switching character sets or calendars for date interpretation, or for indicating an inclusion of a non_GEDCOM data form into the GEDCOM structure. The form of the escape sequence is:

@# escape_text @ non_at.

for example:

@#DJULIAN@.

The non_at after the final at character (@) should be discarded if it is a space ( ). Otherwise, it should be retained as part of the text following the escape. Output systems should always place a space ( ) after the escape sequence.

The specific format of the escape sequence is defined for the specific GEDCOM form being defined. (See chapter 2 for the escape sequence definition for the lineage-linked form).

escape_text:=

The escape_text is defined to meet the requirements of a particular GEDCOM form. For the lineage-linked form the definitions are found in Chap. 2.

level:=

The level number works the same way as the level of indentation in an indented outline, where indented lines provide detail about the item under which they are indented. A line at any level L is enclosed by and pertains directly to the nearest preceding line at level L-1. The Level L may increase by 1 at most. Level numbers must not contain leading zeroes which are not significant, for example level one must be (1), not (01).

The enclosed subordinate lines at level L are said to be in the context of the enclosing superior line at level L-1. The meaning of a tag (see tag below) is interpreted in the context of the tags of the enclosing line(s). Take the following record about an individual's birth and death dates, for example:

0 INDI
  1 BIRT
    2 DATE 12 MAY 1920
  1 DEAT
    2 DATE 1960

In this example, the expression DATE 12 MAY 1920 is interpreted within the INDI (individual) BIRT (birth) context, representing the Individual's birth date. The second DATE is in the INDI DEAT (death) context. The complete meaning of DATE depends on the context. (Note: the above example is indented according to the level numbers to make the concept more obvious. In the actual GEDCOM data there is no indentation, just level numbers lined up vertically on the left margin).

NOTE: Some existing systems provide an option to produce an indented GEDCOM output for user readability, using space or tab characters between the terminator and the level number of the next line to visibly show the hierarchy. Also, some have suggested allowing extra blank lines to visibly separate physical records. These features may be incorporated into the GEDCOM standard at some future time, but for now, such a change would render some existing systems incompatible. Therefore, we recommend that new systems be prepared to discard extra carriage returns, line feeds, spaces and tabs immediately preceding the level number during input. Output should still be constrained to level numbers without indentation or blank lines, until most receiving systems are prepared to deal with this change.

line_value:=

The line_value identifies an object within the domain of possible values allowed in the context of the tag. The combination of the tag, the line_value, and the hierarchical context of the supporting gedcom_lines provides the understanding of the enclosed values. This domain is defined by a specific grammar for representing a given GEDCOM form (see chapter 2 for Lineage-linked grammar).

Values whose source information contains illegible parts of the value should be indicated by replacing the illegible part with ... (ellipses).

Values are generally not encoded in binary or other abbreviation schemes for reducing space requirements, and they are generally constrained to be understandable by a typical user without decoding. This is intended to reduce the decoding burden on the receiving software. A GEDCOM-optimized data compression standard will be defined in the future to reduce space requirements. Meanwhile, users may agree to compress and decompress GEDCOM files using any compression system available to both sender and receiver.

The line_value within the context of a tag hierarchy of gedcom_lines represents one piece of information and corresponds to one field in traditional database or file terminology.

opt_xref_id:=

(See pointer.)
The opt_xref_id is formed by any arbitrary combination of characters from the pointer_char set. The first character must be an alpha or a digit. The opt_xref_id is not retained in the receiving system, and may therefore be formed from any convenient combination of identifiers from the sending system. No meaning is attributed by the receiver to any part of the opt_xref_id, other than its unique association with the associated record. The use of the colon (:) character is also reserved.

otherchar:=

[(0x21)-(0x22) | (0x24)-(0x2F) | (0x3A)-(0x3F) | (0x5B)-(0x5E) | (0x60) | (0x7B)-(0x7E) | (0x80)-(0xFF)]
Any ASCII character except control characters (0x00 - 0x1F), alphanum, space ( ), number sign (#), at character (@), and the DEL character (0x7F).

If any of these characters appear in the level, xref_ID, or pointer segments of the GEDCOM line, then that substructure should be written to an exception file. If any of these characters appear in the value segment and the proper escape processing has not been invoked, then they should be replaced by a (^) (0x5E) character, unless the character is a TAB (0x09) character which can be replaced with a space (0x20) character. These changes should also be recorded on an exception file.

pointer:=

A pointer stands in the place of the context identified by the matching xref_id. Theoretically, a receiving system should be prepared to follow a pointer to find any needed value in a manner that is transparent to the logic of the subsystem that is looking for specific tags. This highly-flexible facility will probably be used more in the future. For the time being, however, the use of pointers is explicitly defined within the GEDCOM form (Such as defined in Chapter 2).

The pointer represents the association between two objects that usually reside in different records. There can, however, be an association between objects within the same logical record. If this condition exists it is indicated in the pointer record composition containing an (!) character that separates the parent record's cross-reference ID from the specific substructure's cross-reference ID which is at some subordinate level to the logical at level zero. The cross-reference ID of the substructure subordinate to a zero level record is always composed of the Record ID number and the Substructure ID number, such as @I132!1@. By including the Record Id number in the pointers which associate objects within a record will allow the GEDCOM processors to build the index only at the record level and then search sequentially for the appropriate substructure cross reference ID.

Complex logical record structures are divided into small physical records to accommodate memory constraints, many-to-many relationships, and independent record creation and deletion.

The pointer must match a corresponding xref_id within the transmission, unless the colon (:) character is present (future network reference to a permanent file record). A pointer is given instead of duplicating an object, though the logical result is equivalent. An expanded traversal of a record tree includes following the pointers to related records to some depth, and splicing those records (logically) into the resultant expanded tree. Pointers may refer to either records which have not yet appeared in the transmission (forward reference) or to records that have already appeared earlier in the transmission (backward reference). This arrangement usually requires a preliminary pass to construct a look up table to support random access by xref_id during subsequent passes.

tag:=

A tag consists of a variable length sequence of alphanum characters. All user defined tags, that is tags used which have not been defined by the GEDCOM standard must begin with an underscore character. (0x95). All user defined tags must be defined in the SCHEMA substructure of the HEADer record.

The tag represents the meaning of the line_value within the context of the enclosing lines, and contributes to the meaning of enclosed subordinate lines. Specific tags are defined in Appendix A.

Although existing tags are only three or four characters long, systems should prepare to handle tags of any length. Tags will be unique within the first 15 characters.

Valid combinations of specific tags, line_values, xref_ids, and pointers are constrained by the GEDCOM form defined for representing a given kind of information (see chapter 2 for the Lineage-linked form grammar).

terminator:=

The terminator delimits the variable-length line_value and signals the end of the gedcom_line. The valid terminator characters are:

[ carriage_return | line_feed | carriage_return line_feed | line_feed carriage_return ]

Examples:

The following are examples of valid but unrelated GEDCOM-lines:

• 0 @1234@ INDI
• 1 AGE 13
• 1 CHIL @1234@
• 1 NOTE This is a note field that is
2 CONT continued on the next line.

The first line has a level number 0, a xref_id of @1234@, an INDI tag, and no value. The second line has a level number 1, no xref_id, an AGE tag, and a value of 13. The third line has a level number 1, no xref_id, a CHIL tag, and a value of a pointer to a xref_id named @1234@.