Validation-rule catalog

This is a structured catalog of what the validator checks, organised by the kind of problem rather than tag by tag. The same engine drives the editor squiggles and the validation panel — see Validation: reading, fixing, silencing for how to read, fix, and silence results. This page is the reference that guide points into.

It is representative, not exhaustive. There are hundreds of per-tag rules, and they differ by GEDCOM version. The exhaustive source is twofold: the per-version rule definitions Linea Codex runs against, and the embedded spec viewer, which is the live per-tag truth — for any tag it shows what the value may be, where the tag is valid, and what may nest beneath it. When a category below says “depends on the rule,” the spec viewer is where you confirm the specifics for a given tag.

Severity is a default, not a verdict

Most rules ship with a default severity, and you can silence a rule you don’t need — from the validation panel (right-click → Silence rule) or Settings → Validation Rules — so it stops reporting. The severities in the tables below are those shipped defaults. The few checks marked (fixed) are different: they’re emitted directly by the engine rather than from the per-version rule files, so their severity is constant and they always report — silencing doesn’t apply to them.

Severities

Three levels, in order of urgency:

Severity	Meaning
Error	The file departs from the specification here; another program may reject or misread it.
Warning	Valid, but likely a mistake or worth a second look.
Info	An advisory hint, no action implied.

Validation never blocks an operation — it reports. You can edit, convert, and export a file that still has errors; the validator’s job is to tell you, not to stop you.

Rule categories

Category	What it catches	Default severity	Version notes
Structural root	A standard tag placed under a custom (_-prefixed) tag, outside its documented context.	Warning (fixed)	5.5 / 5.5.1 only. In 7.0 a standard tag inside an extension subtree is permitted (the extension governs its own shape), so nothing is reported.
Unknown tag	A non-underscore tag the version’s grammar doesn’t define (e.g. a typo like BRIT for BIRT).	Error (fixed)	Version-specific: a tag known in one version may be unknown in another. Custom _-prefixed tags are never flagged here — they’re a deliberate extension mechanism, not an error.
Cardinality — too few	A required substructure is missing, or appears fewer times than the minimum (e.g. in 7.0 a name TRANslation with no LANG child, which is required there).	Depends on the rule	Min/max counts are per-version; a structure required in one version may be optional or absent in another.
Cardinality — too many	A substructure repeated beyond its allowed maximum (e.g. two SEX lines under one INDI).	Depends on the rule	As above.
Required / forbidden child	A mandatory child tag is absent, a forbidden one is present, mutually-exclusive children co-occur, or an “at least one of” set is empty.	Depends on the rule	Which children are required/forbidden is per-version.
Enumerated value	A value outside the permitted set (e.g. a SEX other than M / F / U / X). Covers single-value and comma-separated list enumerations.	Depends on the rule	Permitted value sets differ by version (7.0 widened several enumerations).
Value required / forbidden	A tag that must carry a value has none, or a tag that must not carry one does (e.g. a structural record tag like INDI, whose own line carries no value).	Depends on the rule	Per-version.
Value format	A value that doesn’t match its expected shape — a number out of range, text the wrong length, a pattern mismatch, or a payload a typed parser (date, age, etc.) rejects.	Depends on the rule	Format rules (notably dates) are version-sensitive — see Dates & places.
Pointer required / forbidden	A tag that must point to a record carries no cross-reference, or one that must not is given an xref id.	Depends on the rule	Per-version.
Reference integrity	A pointer @X1@ that resolves to no record, or resolves to the wrong kind of record (e.g. a HUSB pointing at a SOUR).	Depends on the rule	In 7.0 the literal @VOID@ is a deliberate null pointer and is exempt; in 5.5 / 5.5.1 it’s an ordinary xref that must resolve.
Reference cycle	A loop in pointer chains that must stay acyclic (e.g. a record listed among its own ancestors).	Depends on the rule	The engine can detect cycles, but only over pointer chains a version’s rules mark as acyclic; this fires only where such a rule is defined.
Conditional requirement	A rule that only applies in context — a child or value required (or forbidden) because of another tag, value, or xref present on the structure.	Depends on the rule	Per-version.
Undeclared extension	A custom _-prefixed tag used without being declared in the header schema (HEAD.SCHMA).	Warning (fixed)	7.0 only. 5.5 / 5.5.1 have no schema mechanism, so this check doesn’t run there.
Media / crop	A CROP region that falls outside the image, or a crop targeting a non-image file.	Depends on the rule	Applies to multimedia structures; needs image metadata to evaluate, and is skipped silently when none is available.
File reference	A FILE, TRAN, or _EMBED path that doesn’t point to a file in your project.	Warning (broken / absolute / file://); Info (remote URL); Error (empty value)	Version-independent — this check is about your project’s files, not the GEDCOM grammar. See Media & files.

On the version notes

The most important thing this catalog can tell you is that validity is version-specific. A structure that’s perfectly valid in GEDCOM 7.0 may be flagged in 5.5, and vice versa — Linea Codex always checks against your project’s declared version. Two concrete examples from the rule definitions:

• FONE (a phonetic-variation tag) is valid in 5.5.1 only — it didn’t exist in 5.5, and 7.0 removed it in favour of TRAN, so a FONE line is flagged in both 5.5 and 7.0.
• BLOB (inline binary multimedia) is valid in 5.5 but removed in 5.5.1 and 7.0 — later versions use file-based multimedia instead.

That a rule file exists for a tag in a given version does not mean the tag is valid there — “not valid here” is recorded as an explicit empty rule set. So don’t infer validity from anything but the rules themselves, surfaced for you in the spec viewer.

When you convert between versions — or relabel a file’s version — validation re-runs against the new version’s rules, which is exactly why a freshly converted file may surface a different set of issues. Conversion is best-effort: a compliant file converts to a compliant file, but a downgrade can’t always preserve everything, and the validator is how those gaps become visible.

Custom tags are first-class

Two of the categories above turn on the underscore convention, and it’s worth stating plainly: a _-prefixed custom tag is never an “unknown tag” error. Custom tags are how GEDCOM lets you record things the standard has no tag for — see When GEDCOM has no tag for it. The only custom-tag check is the 7.0 reminder to declare your extensions in the header schema (the “undeclared extension” warning above), so other programs know what your tags mean.

Where to go from here

• To act on results — read them, jump to them, fix or silence them — see Validation: reading, fixing, silencing.
• To understand why a specific tag is flagged, look it up in the spec viewer — the authoritative per-tag reference.
• To fix an issue across many records at once, use the bulk transform rule builder; the editor’s inline quick-fixes handle a few well-defined spot cases.
• To manage which rules run, open Settings → Validation Rules.