Diagnostics reference¶
Every diagnostic has a stable code. A code never changes meaning within a major version; new codes may be added in minor releases. Messages are informative and may change.
| Range | Level |
|---|---|
KV1xxx |
Syntax: line format, levels, encoding, HEAD/TRLR |
KV2xxx |
Structure: allowed substructures and cardinality |
KV3xxx |
Values: payload presence and data types, dates |
KV4xxx |
References: dangling and duplicate xrefs, record types, family links |
KV5xxx |
Plausibility, optional: dates and pedigrees that cannot be true |
KL0001–KL9999 |
Loss report entries of conversions, see losses.md |
KV1 — syntax¶
| Code | Severity | Meaning |
|---|---|---|
KV1001 |
warning (info for an empty line) | The line is not level [xref] tag [value]; it is kept verbatim and ignored by the model |
KV1002 |
error | Level jumps by more than one; the line is attached to the deepest open structure |
KV1003 |
error | Bytes are invalid in the detected encoding; the value is decoded with U+FFFD, the original bytes are kept for writing |
KV1004 |
error | The first record is not HEAD |
KV1005 |
error | TRLR is missing |
KV1006 |
warning | Records follow TRLR |
KV1007 |
warning | HEAD.GEDC.VERS is missing; the file is read as 5.5.1 |
KV1008 |
warning | HEAD.GEDC.VERS names an unknown version; the file is read as 5.5.1 |
KV1009 |
info | HEAD.GEDC.VERS names GEDCOM 4.0 (4.0, 4.0.4.18, 4+), read as Version::V4_0, or a 5.0–5.4 draft (5.3, 5.01), read as 5.5: both with the 5.5 profile (conversion.md) |
KV1010 |
info | A documented mistake of the program that wrote the file is corrected: the file is read in another encoding or version than it declares (dialects.md); ReadOptions::withDialects(false) turns it off |
KV1101 |
warning | HEAD.CHAR is not a standard value (e.g. ANSI, LATIN1); the encoding is detected from content |
KV1102 |
warning | HEAD.CHAR contradicts the content; the content wins |
KV1103 |
info | No usable HEAD.CHAR; the encoding is guessed from content |
KV1104 |
warning | 5.5.5: the file does not start with a byte order mark ("All GEDCOM 5.5.5 files … must start with a Byte Order Mark"). Reported by Gedcom::validate() for the file, without a line; a warning, because the BOM carries no data |
KV1201 |
warning | GEDZIP: an entry name is not a safe relative path (.., an absolute path, \, a drive letter, a control character); the entry is ignored. Reported by Gedcom::readGedzip() in Archive::diagnostics() |
KV1202 |
warning | GEDZIP: an entry is a symbolic link; it is ignored |
KV1203 |
warning | GEDZIP: gedcom.ged is not GEDCOM 7.0; it is read as what it declares |
KV1204 |
warning | GEDZIP: a FILE reference that is a relative path names no entry of the archive |
In strict mode (ReadOptions::withStrict()) every error-level KV1 diagnostic throws
ParseException instead.
KV2 — structure¶
Reported by Gedcom::validate() against the profile of the document's version. Extension tags
(_X) and everything under them are not checked. reference names the profile term of the
structure that contains the problem: a 7.0 term such as https://gedcom.io/terms/v7/record-INDI,
or for 5.x a place in the grammar of the specification such as
https://gedcom.io/specifications/ged551.pdf#INDIVIDUAL_RECORD/INDI
(5.5.5: https://www.gedcom.org/specs/GEDCOM555.zip#…).
| Code | Severity | Meaning |
|---|---|---|
KV2001 |
error | A standard tag that is not allowed where it stands (in this superstructure, or as a record); its substructures are not checked. 5.x citations and media links are checked by their form: TEXT is not allowed in SOUR with a pointer |
KV2002 |
error | A substructure occurs more often than allowed; reported once, at the first extra occurrence. Also the second of two substructures of which 7.0 allows one (HEAD allows one of NOTE and SNOTE) |
KV2003 |
error | A required substructure is missing; reported at the structure that lacks it. A missing required record (5.5.5: SUBM) is reported for the file, without a line |
KV2004 |
error | 5.5.5: the SUBM record does not directly follow HEAD; reported at the first SUBM record. Extension records do not count |
KV2005 |
warning | 7.0: a structure or value the specification deprecates: ADR1, ADR2, ADR3, HEAD.SOUR.DATA, EXID without TYPE, and the STAT values COMPLETED, EXCLUDED, INFANT, PRE_1970, SUBMITTED, UNCLEARED. The message says what to write instead where the specification does. The list is spec/7.0/deprecations.yaml |
Every code can be left out or reported with another severity:
$options = (new ValidationOptions())->withDisabled('KV2001')->withSeverity('KV1101', Severity::Error);
$report = Gedcom::validate($doc, $options);
KV3 — values¶
Reported by Gedcom::validate() for every version against the payload of each standard
structure; extension structures are not checked. Messages name the expected type and never
quote a value, except an enumeration value shortened to 20 characters.
- 7.0: the data types of specification chapter 2. Dates follow the
DateValue,DatePeriodandDateExactgrammars with the months and epochs of their calendar (GREGORIANwhen none is given). The months, epochs and days of an extension calendar are not checked, nor extension months and epochs in a standard calendar. - 5.5 and 5.5.1: the primitive elements of
spec/<version>/primitives.yaml; other elements are text, and field sizes are recommendations, not checked. Enumerations, date keywords and months are case-insensitive. Dates areDATE_VALUE,DATE_PERIODorDATE_EXACTwith calendar escapes (@#DJULIAN@), date phrases in parentheses,B.C.after any year (44 B.C.,MAR 44 B.C.) and Gregorian dual years (1648/49). - 5.5.5: the primitive elements of
spec/5.5.5/primitives.yamlwith the stricter grammars of 5.5.5: years of 3 or 4 digits, days without a leading zero,BCE,BCorB.C.after a lone Gregorian or Julian year, Gregorian and Julian dual years with a month,23 AUGwithout a year, no@#DROMAN@; ages with</>and without zero parts or leading zeroes (at most999y 11m 365d); timesh:mm[:ss[.ff]]; version numbers; place names in parts separated by,. Text values are checked against their{Size=min:max}(KV3010). The file must start with a BOM (KV1104) andSUBMdirectly followHEAD(KV2004). Rules given only in prose (no digits in names, dual years only from 1 January to 24 March and up to 1923) are not checked.
| Code | Severity | Meaning |
|---|---|---|
KV3001 |
error | A value is required but missing (7.0: Text, List:Text, Age, DateValue, DatePeriod and Y\|<NULL> may be omitted, as long as the structure has substructures (KV3007); 5.x: payloads with <NULL>) |
KV3002 |
error | The structure must not have a value |
KV3003 |
error | The value must be a pointer to a record |
KV3004 |
error | A pointer where a value is expected (in 7.0 a leading @ of text is written @@) |
KV3005 |
error | The value does not match its data type. 7.0: integer, personal name, BCP 47 language, media type, age, time, latitude, longitude, file path, URI, tag definition, Y, dates (including a day outside 1–36). 5.x: age, time, number, personal name, Y, dates; 5.5.1 and 5.5.5 also latitude, longitude; 5.5.5 also version numbers and place names |
KV3006 |
error | An enumeration value that the structure does not permit (5.5.5 also HEAD.GEDC.FORM, which must be LINEAGE-LINKED); in 7.0 extension values (_X) are always permitted |
KV3007 |
error | 7.0 and 5.5.5: a structure with neither a value nor substructures (TRLR excepted; a missing required substructure is KV2003). 5.5.5: "every GEDCOM record without subrecords must have a line value" |
KV3008 |
warning | A date whose day is beyond the length of its month: 31 NOV, 29 FEB 1900, FRENCH_R 7 COMP. February follows the leap years of its calendar; Hebrew months use their longest length |
KV3009 |
warning | 5.x: a dual year whose second year does not follow the first, such as 1701/99 (1701/02 is meant) |
KV3010 |
error | 5.5.5: a text value shorter or longer than its {Size=min:max}, counted in characters of the value with its CONC/CONT lines. A value the specification lists for the element is valid whatever its length (NAME.TYPE aka, FONE.TYPE kana: {Size=5:30}) |
KV4 — references¶
Reported by Gedcom::validate() in every version; KV4003 needs the version's profile. Xrefs are
case-sensitive (@test@ is not @TEST@). In 7.0 @VOID@ is a null pointer and never dangles.
7.0 tag definitions. A documented extension tag is an abbreviation for its URI (specification
chapter 1, "Extension tags"). When HEAD.SCHMA gives an extension tag the URI of a standard
record type, calendar or month, it is checked as that: after 2 TAG _USER
https://gedcom.io/terms/v7/record-SUBM, SUBM @U1@ may point to 0 @U1@ _USER (its contents
are an extension's and are not checked), and after 2 TAG _CAL https://gedcom.io/terms/v7/cal-JULIAN
the date _CAL 1 MAR 1700 is a Julian date.
| Code | Severity | Meaning |
|---|---|---|
KV4001 |
error (warning in an extension) | Pointer to a record that does not exist. In an extension structure or inside one it is a warning: what an extension points to is not defined (_FAMC @VOID@, a 7.0 null pointer kept in 5.5.1) |
KV4002 |
error | Xref already used by an earlier record; pointers resolve to the first one |
KV4003 |
error | Pointer to a record of the wrong type, e.g. FAMC to an INDI |
KV4004 |
warning | A family link is not mutual: INDI.FAMC without FAM.CHIL, INDI.FAMS without FAM.HUSB/WIFE, or the reverse; only checked when the target exists |
KV5 — plausibility¶
Optional: reported only with ValidationOptions::withPlausibility(), always as warnings, for
data that is valid but cannot be true. Dates are compared only when the conflict is certain:
a date stands for every day it can mean (1907 is the whole year, BEF 1907 has no first
day, BET 1900 AND 1910 spans both years, as does BET 1910 AND 1900). Gregorian and Julian dates of every version are
compared, including B.C./BCE and dual years (1648/49 is 1649); approximate dates (ABT,
CAL, EST), date phrases and other calendars are not. The first BIRT and DEAT with
such a date count. Parents are HUSB and WIFE of the families an individual is a child of,
by FAM.CHIL or INDI.FAMC.
$report = Gedcom::validate($doc, (new ValidationOptions())->withPlausibility());
| Code | Severity | Meaning |
|---|---|---|
KV5001 |
warning | A birth after the death, reported at the birth date |
KV5002 |
warning | A child born before a parent, reported at FAM.CHIL |
KV5003 |
warning | An individual who is their own ancestor, reported once per cycle, at its first individual |