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-john-smith
    claim: 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

Required Fields

Entity ID (map key)

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

subject

• Type: String
• Required: Yes
• Description: The entity this assertion is about (person, event, relationship, etc.)

Example:

subject: person-john-smith

claim

• Type: String
• Required: Yes
• Description: The property or fact being claimed

Common claim types:

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

Example:

claim: occupation

Evidence Requirement

At least ONE of the following is required:

• citations - Array of citation IDs
• sources - Array of source IDs (direct source references)

Example:

citations:
  - citation-birth-cert
  - citation-baptism-record

Optional Fields

participant

• Type: Object
• Required: No (mutually exclusive with claim and value)
• Description: Used for assertions about a person's participation in an event or relationship (instead of claiming 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, claim and value must NOT be present
• When participant is present, the implicit claim is "participant"
• Useful for representing conflicting evidence about who participated in an event or relationship

Example:

assertions:
  assertion-witness-john:
    subject: 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: No for participant assertions; recommended for claim assertions
• Description: The concluded value of the claim (not used with participant)

Example:

claim: occupation
value: blacksmith

confidence

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

Standard levels:

• high - Multiple primary sources agree
• medium - Some conflicting evidence, but preponderance supports
• low - Limited evidence, requires more research
• disputed - Multiple sources conflict, resolution unclear

See Vocabularies - Confidence Levels for:

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

Example:

confidence: high

research_notes

• Type: String
• Required: No
• Description: Detailed research notes explaining the conclusion

Example:

research_notes: |
  Two conflicting sources:
  - Birth certificate: January 15, 1850 (preferred, higher quality)
  - Baptism record: January 20, 1850 (5-day delay common)
  
  Certificate takes precedence as primary direct evidence.

evidence_type

• Type: String
• Required: No
• Description: Quality classification of evidence

Values:

• primary-direct - Created at time of event by witness
• primary-indirect - Created at time, but not direct witness
• secondary-direct - Later account from witness
• secondary-indirect - Later account from non-witness

Example:

evidence_type: primary-direct

type

• Type: String
• Required: No
• Description: Classification of assertion type

Example:

type: biographical

notes

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

Provenance Fields

Property	Type	Description
modified_at	datetime	When last modified
modified_by	string	Who last modified

Example:

modified_at: "2024-03-20T14:15:00Z"
modified_by: researcher-john

tags

• Type: Array of Strings
• Required: No
• Description: Tags for categorization

Example:

tags:
  - needs-review
  - conflicting-evidence
  - high-priority

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-marriage-participants.glx
assertions:
  assertion-john-married:
    subject: event-marriage-1880
    participant:
      person: person-john-smith
      role: groom
    citations:
      - citation-marriage-cert
    confidence: high
  
  assertion-jane-married:
    subject: event-marriage-1880
    participant:
      person: person-jane-doe
      role: bride
    citations:
      - citation-marriage-cert
    confidence: high
  
  assertion-witness-thomas:
    subject: event-marriage-1880
    participant:
      person: person-thomas-brown
      role: witness
      notes: "Witnessed marriage ceremony"
    citations:
      - citation-marriage-cert
    confidence: high

Conflicting Participant Evidence

# assertions/assertion-conflicting-parents.glx
assertions:
  # One source claims person-john is the father
  assertion-john-father-cert:
    subject: 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-birth-1850
    participant:
      person: person-thomas-brown
      role: parent
      notes: "Family letter suggests Thomas was the father"
    citations:
      - citation-family-letter
    confidence: low
    research_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.

Usage Patterns

Basic Biographical Assertion

# assertions/assertion-john-birth.glx
assertions:
  assertion-john-birth-date:
    subject: person-john-smith
    claim: born_on
    value: "1850-01-15"
    citations:
      - citation-birth-certificate
    confidence: high

Assertion with Multiple Evidence Sources

# assertions/assertion-john-occupation.glx
assertions:
  assertion-john-occupation:
    subject: person-john-smith
    claim: occupation
    value: blacksmith
    citations:
      - citation-1851-census
      - citation-trade-directory
      - citation-parish-record
    confidence: high
    evidence_type: secondary-direct

Assertion with Conflicting Evidence

# assertions/assertion-mary-birth.glx
assertions:
  assertion-mary-birth-disputed:
    subject: person-mary-jones
    claim: born_on
    value: "1852-03-10"
    citations:
      - citation-birth-cert       # Says March 10
      - citation-family-bible      # Says March 12
    confidence: medium
    research_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)

Complex Residence Assertion

# assertions/assertion-residence.glx
assertions:
  assertion-john-residence-1851:
    subject: person-john-smith
    claim: residence
    value: "Wellington Street, Leeds, Yorkshire"
    citations:
      - citation-1851-census
      - citation-directory-1851
    confidence: high
    evidence_type: primary-direct
    notes: "Residence at time of 1851 census"
    tags:
      - census-derived
      - verified

Low Confidence Assertion

# assertions/assertion-estimated-birth.glx
assertions:
  assertion-thomas-birth-estimated:
    subject: person-thomas-brown
    claim: born_on
    value: "circa 1825"
    citations:
      - citation-death-cert-age
    confidence: low
    research_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
    tags:
      - estimated
      - needs-research

Evidence Quality and Confidence

Assertions connect evidence quality (from citations) to confidence in conclusions:

Citation Quality Scale (GEDCOM QUAY)

Quality	Description	Example
0	Unreliable	Unverified online tree
1	Questionable	Secondary source with errors
2	Secondary	Death certificate for birth info
3	Primary	Birth certificate

Assertion Confidence

Confidence	Criteria	Example
high	Multiple quality-3 sources agree	3 birth certificates with same date
medium	Preponderance of evidence, some conflict	2 sources agree, 1 disagrees
low	Limited evidence, needs research	Only one low-quality source
disputed	Conflicting evidence, no clear resolution	Multiple primary sources disagree

Validation Rules

• subject must reference an existing entity ID
• At least one of citations or sources must be present
• All citation references must point to existing Citation entities
• All source references must point to existing Source entities
• confidence should be one of: high, medium, low, disputed
• evidence_type should follow standard classifications if used

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 other entity
    ├── citations → array of Citation IDs (evidence)
    └── sources → array of Source IDs (direct reference)

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

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

GEDCOM Mapping

GENEALOGIX assertions are implicit in GEDCOM:

GENEALOGIX	GEDCOM Equivalent
Assertion	Implicit in INDI/FAM + SOUR structure
subject	INDI or FAM record
claim	Property tag (BIRT, DEAT, OCCU, etc.)
value	Property value
citations	SOUR tags on property
confidence	Derived from QUAY values

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:
      given_name: "John"
      family_name: "Smith"

assertions:
  assertion-john-birth:
    subject: person-john-smith
    claim: 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 Hierarchy - Understanding evidence quality
• Citation Entity - Evidence references that support assertions
• Source Entity - Original sources cited by assertions
• Person Entity - Common subject of assertions
• Data Types