Assertion Entity

← Back to Entity Types

Overview

An Assertion entity represents a source-backed conclusion about a specific genealogical fact. Assertions form the core of the GENEALOGIX evidence model, separating what sources say (citations) from what we conclude (assertions).

This separation enables:

• Multiple evidence sources supporting a single conclusion
• Conflicting evidence representation
• Confidence assessment based on evidence quality
• Clear research transparency and audit trails

File Format

All GENEALOGIX files use entity type keys at the top level:

# Any .glx file (commonly in assertions/ directory)
assertions:
  assertion-john-birth-date:
    subject:
      person: person-john-smith
    property: born_on
    value: "1850-01-15"
    citations:
      - citation-birth-certificate
    confidence: high

Key Points:

• Entity ID is the map key (assertion-john-birth-date)
• IDs can be descriptive or random, 1-64 alphanumeric/hyphens

Fields

Required Fields

Field	Type	Description
Entity ID (map key)	string	Unique identifier (alphanumeric/hyphens, 1-64 chars)
subject	object	Typed reference to the entity this assertion is about
citations, sources, or media	array	At least one required (enforced by JSON Schema and CLI validation)

Optional Fields

Field	Type	Description
property	string	Property being asserted (mutually exclusive with participant; when omitted, assertion is existential)
participant	object	Participant in an event or relationship (mutually exclusive with property/value)
value	string	The concluded value of the property (required when property is present; not used with participant)
date	string	Date or date range: when property is present, specifies when the value applies; on existential assertions, indicates when the subject existed
confidence	string	Confidence level (defined in archive vocabulary)
notes	string	General notes about the assertion
status	string	Research status of this assertion (e.g., proven, disproven, speculative)

Subject Object

The subject field uses a typed reference to avoid entity ID collisions. Exactly one key must be present:

Field	Type	Description
person	string	Reference to a Person entity
event	string	Reference to an Event entity
relationship	string	Reference to a Relationship entity
place	string	Reference to a Place entity

Participant Object Fields

Field	Type	Required	Description
person	string	Yes	Reference to the person entity
role	string	No	Role of the participant
properties	object	No	Per-participant properties (validated against event_properties vocabulary for event subjects, relationship_properties for relationship subjects)
notes	string	No	Notes about this participant

Required Fields

Entity ID (map key)

• Format: Any alphanumeric string with hyphens, 1-64 characters
• Must be unique within the archive
• Example formats:
  • Descriptive: john-birth-date, mary-occupation
  • Random hex: a1b2c3d4
  • Prefixed: assertion-a1b2c3d4
  • Sequential: 001, 002

subject

• Type: Object with exactly one typed reference field
• Required: Yes
• Description: The entity this assertion is about (person, event, relationship, or place)

The typed reference structure prevents entity ID collisions in large archives where different entity types might have the same ID.

Examples:

# Asserting about a person
subject:
  person: john-smith

# Asserting about an event
subject:
  event: marriage-1880

# Asserting about a relationship
subject:
  relationship: parent-child-001

# Asserting about a place
subject:
  place: leeds-yorkshire

property (or participant)

• Type: String (for property) or Object (for participant)
• Required: No — both are optional and mutually exclusive. When neither is present, the assertion is an existential assertion.
• Description: Either a property name being asserted, or a participant object for event/relationship participation

Note: The property field corresponds to property names defined in property vocabularies. For example, property: born_on references the born_on property from the person properties vocabulary. Unknown properties generate validation warnings.

Common property types:

• born_on - Birth date
• died_on - Death date
• born_at - Birth place
• occupation - Occupation/profession
• residence - Residence location
• name - Name form

Example:

property: occupation

Evidence Requirement

At least ONE of the following is required:

• citations - Array of citation IDs
• sources - Array of source IDs (direct source references)
• media - Array of media IDs (direct visual or documentary evidence)

When to use each:

• citations (preferred): When you have specific details about where in a source the evidence is found - page 23, entry 145, specific URL. This is rigorous and allows others to find the exact evidence.

• sources (direct): When the source doesn't need sub-location details:

  • Single-page documents (birth certificate) where a citation adds no value
  • Photographs or brief documents without meaningful subdivisions
  • Preliminary research where you'll add specific citations later

• media (direct visual evidence): When media itself is the evidence, without a formal source or citation:

  • Gravestone photos directly evidencing dates and names
  • Family photographs evidencing relationships or locations
  • Handwritten documents or letters where the media is the primary evidence

Example:

citations:
  - citation-birth-cert
  - citation-baptism-record
media:
  - media-gravestone-photo

Optional Fields

participant

• Type: Object
• Required: No (mutually exclusive with property and value)
• Description: Used for assertions about a person's participation in an event or relationship (instead of asserting a property value)

Structure:

participant:
  person: "person-id"    # Reference to the person (required)
  role: "participant-role"  # Role of the participant (optional)
  notes: "string"        # Notes about the participant (optional)

Key Points:

• When participant is present, property and value must NOT be present
• Useful for representing conflicting evidence about who participated in an event or relationship

Example:

assertions:
  assertion-witness-john:
    subject:
      event: event-marriage-1880
    participant:
      person: person-john-smith
      role: witness
      notes: "Listed as witness on marriage certificate"
    citations:
      - citation-marriage-cert
    confidence: high

value

• Type: String
• Required: Yes when property is present; not used with participant
• Description: The concluded value of the property

Example:

property: occupation
value: blacksmith

date

• Type: String
• Required: No
• Description: Date or date range. When property is present, specifies when the asserted value was true (matching the temporal value format on entities). On existential assertions (no property or participant), indicates when the subject existed. This field is strictly for temporal targeting — it is NOT an "evidence date" or "observation date".

When a temporal property on an entity has multiple dated values:

# Person's temporal property
occupation:
  - value: "blacksmith"
    date: "FROM 1870 TO 1890"
  - value: "farmer"
    date: "FROM 1890 TO 1920"

Each assertion can target a specific temporal entry using date:

assertions:
  assertion-occupation-blacksmith:
    subject:
      person: person-john-smith
    property: occupation
    value: "blacksmith"
    date: "FROM 1870 TO 1890"
    citations: [citation-1881-census]
    confidence: high

Date formats follow the standard date format. If omitted, the assertion applies to the property value without temporal context.

confidence

• Type: String
• Required: No
• Description: Confidence level based on evidence quality

Confidence levels and their criteria are defined in each archive's vocabularies/confidence-levels.glx file. The standard vocabulary provides these defaults:

• high - Multiple high-quality sources agree, minimal uncertainty
• medium - Some evidence supports conclusion, but conflicts or gaps exist
• low - Limited evidence, significant uncertainty
• disputed - Multiple sources conflict, resolution unclear

Archives can customize these descriptions or add additional levels to match their research methodology.

See Vocabularies - Confidence Levels for:

• Customizing confidence level definitions for your archive
• Adding custom confidence levels
• Vocabulary file structure and validation

Example:

confidence: high

status

• Type: String
• Required: No
• Description: Research status of the assertion, tracking where it stands in the research process

Unlike confidence (which measures how certain you are about the claim), status records the verification state of the assertion itself. Common values include:

• proven — verified through primary evidence
• speculative — a hypothesis that needs further research
• disproven — evidence has been found that contradicts this assertion

These values are free-text; archives may use any status labels appropriate for their research methodology.

Example:

# High confidence but not yet verified
confidence: high
status: speculative

# High confidence and verified
confidence: high
status: proven

# High confidence that this is wrong
confidence: high
status: disproven

notes

• Type: String
• Required: No
• Description: General notes about the assertion

Participant Assertions

Participant assertions represent evidence about who participated in an event or relationship, including conflicting evidence about participation and roles.

Participant Assertion Example

assertions:
  assertion-john-married:
    subject:
      event: event-marriage-1880
    participant:
      person: person-john-smith
      role: groom
    citations:
      - citation-marriage-cert
    confidence: high

  assertion-jane-married:
    subject:
      event: event-marriage-1880
    participant:
      person: person-jane-doe
      role: bride
    citations:
      - citation-marriage-cert
    confidence: high

  assertion-witness-thomas:
    subject:
      event: event-marriage-1880
    participant:
      person: person-thomas-brown
      role: witness
      notes: "Witnessed marriage ceremony"
    citations:
      - citation-marriage-cert
    confidence: high

Conflicting Participant Evidence

assertions:
  # One source claims person-john is the father
  assertion-john-father-cert:
    subject:
      event: event-birth-1850
    participant:
      person: person-john-smith
      role: parent
      notes: "Listed as father on birth certificate"
    citations:
      - citation-birth-cert
    confidence: high

  # Another source claims person-thomas is the father
  assertion-thomas-father-letter:
    subject:
      event: event-birth-1850
    participant:
      person: person-thomas-brown
      role: parent
      notes: "Family letter suggests Thomas was the father"
    citations:
      - citation-family-letter
    confidence: low
    notes: |
      Conflicting evidence about paternity:
      - Birth certificate (primary source): John Smith
      - Family letter (secondary source): Thomas Brown

      Certificate is more reliable, but letter provides alternative possibility.
      Needs further research.

Existential Assertions

An assertion with neither property nor participant is an existential assertion — it asserts that the subject entity exists, backed by evidence. This is the simplest form of assertion: "this entity is evidenced by these sources."

Basic Existential Assertion

assertions:
  assertion-webb-family:
    subject:
      relationship: rel-webb-parent-child
    citations:
      - citation-1860-census-webb
    confidence: high
    notes: "Census shows R. Webb (45) as head of household with these children"

Temporal Existential Assertion

When a date is present without property, the assertion reads as "the subject existed at this time":

assertions:
  assertion-webb-1860:
    subject:
      relationship: rel-webb-parent-child
    date: "1860"
    citations:
      - citation-1860-census-webb
    confidence: high

Existential assertions are particularly useful for:

• Relationships — evidencing that a relationship exists without asserting a specific property
• Events — confirming an event occurred, backed by a source
• Places — documenting that a place existed at a given time

Usage Patterns

Basic Biographical Assertion

assertions:
  assertion-john-birth-date:
    subject:
      person: person-john-smith
    property: born_on
    value: "1850-01-15"
    citations:
      - citation-birth-certificate
    confidence: high

Assertion with Multiple Evidence Sources

assertions:
  assertion-john-occupation:
    subject:
      person: person-john-smith
    property: occupation
    value: blacksmith
    citations:
      - citation-1851-census
      - citation-trade-directory
      - citation-parish-record
    confidence: high

Assertion with Conflicting Evidence

assertions:
  assertion-mary-birth-disputed:
    subject:
      person: person-mary-jones
    property: born_on
    value: "1852-03-10"
    citations:
      - citation-birth-cert       # Says March 10
      - citation-family-bible      # Says March 12
    confidence: medium
    notes: |
      Birth certificate (primary source) says March 10, 1852.
      Family Bible (secondary source) says March 12, 1852.

      Certificate is more reliable as primary direct evidence.
      Bible entry may have been written from memory later.

      Conclusion: March 10, 1852 (with some uncertainty)

Temporal Property Assertion

For temporal properties like residence and occupation, the date field specifies when the value applies:

assertions:
  assertion-john-residence-1851:
    subject:
      person: person-john-smith
    property: residence
    value: "place-leeds"
    date: "FROM 1850 TO 1870"
    citations:
      - citation-1851-census
      - citation-directory-1851
    confidence: high

  assertion-john-occupation-blacksmith:
    subject:
      person: person-john-smith
    property: occupation
    value: "blacksmith"
    date: "FROM 1870 TO 1890"
    citations:
      - citation-1881-census
      - citation-trade-directory
    confidence: high

Assertion with Direct Media Evidence

assertions:
  assertion-john-death-date:
    subject:
      person: person-john-smith
    property: died_on
    value: "1920-06-20"
    media:
      - media-gravestone-photo
    confidence: medium
    notes: "Date read directly from gravestone inscription"

Media can also be combined with citations and sources:

assertions:
  assertion-john-death-confirmed:
    subject:
      person: person-john-smith
    property: died_on
    value: "1920-06-20"
    citations:
      - citation-death-cert
    media:
      - media-gravestone-photo
    confidence: high
    notes: "Death certificate corroborated by gravestone inscription"

Low Confidence Assertion

assertions:
  assertion-thomas-birth-estimated:
    subject:
      person: person-thomas-brown
    property: born_on
    value: "ABT 1825"
    citations:
      - citation-death-cert-age
    confidence: low
    status: speculative
    notes: |
      No birth record found. Age at death (1900) reported as 75,
      suggesting birth around 1825. However, age reporting in
      death certificates is often approximate.

      Need to search:
      - Parish registers 1820-1830
      - Census records for age progression

Evidence Quality and Confidence

Assertions connect evidence (from citations) to conclusions with a certain level of confidence.

Assertion Confidence

The standard vocabulary defines these default confidence levels (archives may customize):

Confidence	Criteria	Example
high	Multiple high-quality sources agree, minimal uncertainty	3 birth certificates with same date
medium	Some evidence supports, but conflicts or gaps exist	2 sources agree, 1 disagrees
low	Limited evidence, significant uncertainty	Only one low-quality source
disputed	Multiple sources conflict, resolution unclear	Multiple primary sources disagree

Validation Rules

• subject must be an object with exactly one typed reference field (person, event, relationship, or place)
• The referenced entity must exist in the archive
• At least one of citations, sources, or media must be present (this is validated as an error if missing)
• property and participant are mutually exclusive — an assertion may have one, the other, or neither (existential assertion)
• When property is present, value is required; value cannot appear without property
• All citation references must point to existing Citation entities
• All source references must point to existing Source entities
• All media references must point to existing Media entities
• property values should match properties defined in the appropriate property vocabulary (unknown properties generate warnings)
• Confidence must be from the confidence levels vocabulary

File Organization

Note: File organization is flexible. Entities can be in any .glx file with any directory structure. The example below shows one-entity-per-file organization, which is recommended for collaborative projects (better git diffs) but not required.

Assertion files are typically organized by subject or topic:

assertions/
├── biographical/
│   ├── births/
│   │   ├── assert-john-birth.glx
│   │   └── assert-mary-birth.glx
│   ├── deaths/
│   │   └── assert-john-death.glx
│   └── occupations/
│       └── assert-john-occupation.glx
├── relationships/
│   └── assert-parentage.glx
└── residences/
    └── assert-1851-residence.glx

Or by entity:

assertions/
├── person-john-smith/
│   ├── assert-birth.glx
│   ├── assert-occupation.glx
│   └── assert-death.glx
├── person-mary-jones/
│   └── assert-birth.glx
└── rel-marriage-001/
    └── assert-marriage-date.glx

Relationship to Other Entities

Assertion
    ├── subject → references Person, Event, Relationship, or Place (typed reference)
    ├── citations → array of Citation IDs (evidence)
    ├── sources → array of Source IDs (direct reference)
    └── media → array of Media IDs (direct visual/documentary evidence)

Citation
    └── supports → Assertion (via assertion's citations array)

Media
    └── supports → Assertion (via assertion's media array)
    └── documents → Source or Citation (via media's source field or citation's media array)

Person/Event/Relationship/Place
    └── documented by → Assertion (subject reference)

GEDCOM Mapping

GENEALOGIX assertions are implicit in GEDCOM:

GLX Field	GEDCOM Tag	Notes
Assertion	Implicit in INDI/FAM + SOUR structure
subject	INDI or FAM record	GLX uses typed reference
property	Property tag (BIRT, DEAT, OCCU, etc.)
value	Property value
citations	SOUR tags on property
confidence	(none)	Set by researcher; not derived from GEDCOM

GEDCOM Example:

0 @I1@ INDI
1 NAME John /Smith/
1 BIRT
2 DATE 15 JAN 1850
2 SOUR @S1@
3 QUAY 3

GENEALOGIX Equivalent:

persons:
  person-john-smith:
    properties:
      name:
        value: "John Smith"
        fields:
          given: "John"
          surname: "Smith"

assertions:
  assertion-john-birth:
    subject:
      person: person-john-smith
    property: born_on
    value: "1850-01-15"
    citations:
      - citation-birth-cert
    confidence: high

Schema Reference

See assertion.schema.json for the complete JSON Schema definition.

See Also

• Core Concepts - Assertion-Aware Data Model - Overview of assertion philosophy
• Core Concepts - Evidence Chain - Understanding evidence quality
• Citation Entity - Evidence references that support assertions
• Source Entity - Original sources cited by assertions
• Person Entity - Common subject of assertions
• Core Concepts - Data Types