Understanding GEDCOM's Level/Tag/Value Structure (for Non-Technical Users)

Open a GEDCOM file in a plain text editor and it looks intimidating — dense, repetitive, full of codes. But every single line follows exactly one pattern, and once you can read that pattern, the file stops being a mystery.

The pattern: level, tag, value

Every line in a GEDCOM file has this shape:

LEVEL TAG value

For example:

0 @I1@ INDI
1 NAME John /Smith/
1 SEX M
1 BIRT
2 DATE 1 JAN 1900
2 PLAC Springfield, Illinois

• Level is a number indicating nesting — 0 is top-level, 1 is a direct child of the line above it, 2 is a child of that, and so on.
• Tag is a fixed code like NAME, BIRT (birth), DEAT (death), or FAM (family) that says what kind of data the line holds.
• Value is the actual content — a name, a date, a place — and is optional; some tags (like BIRT above) exist just to group the indented lines under them.

Records and pointers

Level-0 lines starting with something like @I1@ or @F1@ define a record — an individual or a family — that other parts of the file can reference by that same pointer. So a family record might contain:

0 @F1@ FAM
1 HUSB @I1@
1 WIFE @I2@
1 CHIL @I3@

This says: family record F1 has individual I1 as husband, I2 as wife, and I3 as a child — each pointing back to that person's own 0 @I#@ INDI record elsewhere in the file. This pointer system is exactly what breaks when a "dangling reference" error occurs — it means a line points to an @I#@ or @F#@ that doesn't actually exist anywhere else in the file.

The header, and custom tags

Every GEDCOM file opens with a level-0 HEAD record before any individual or family data — it declares the file's GEDCOM version, character encoding, and the software that generated it. This is the first place worth checking when a file behaves strangely, since a mismatched or missing encoding declaration in the header is a common cause of the garbled-name problem covered elsewhere on this site.

You'll also sometimes see tags starting with an underscore, like _UID or _MYCUSTOMTAG. These are non-standard extension tags — a piece of software's own way of storing extra data (an internal ID, a custom field) that isn't part of the official GEDCOM specification. Other programs are supposed to ignore tags they don't recognize rather than fail on them, but not every implementation does this cleanly, which is another source of data appearing to "go missing" when a file moves between programs.

Why this matters when something goes wrong

Most GEDCOM error messages — from FamilySearch, from desktop software, from any validator — describe a problem in terms of this structure: a missing level-0 record a pointer refers to, a tag appearing at the wrong level, a value that doesn't match what the tag expects (like a non-date value under a DATE tag). Once you know the pattern, an error like "line 4021: FAM record references undefined individual @I892@" stops being cryptic — it's telling you a family record points to a person record that isn't in the file, likely because it was deleted or corrupted during an export or a previous edit.

This structural fragility is also part of why larger files carry more risk during upload, as covered in FamilySearch GEDCOM Size and Individual Limits: What We Found — more records means more pointers, and more opportunities for one to break silently during an export, a program migration, or a partial upload.

You don't need to read raw GEDCOM to use it well. The Upload Readiness Checker parses this structure for you and translates structural problems into plain language — this guide is here for the moments you want to understand what it's actually finding.