Assertion Workflow Example

This example demonstrates the two approaches to recording genealogical data in GLX and when to use each.

The Two Approaches

Approach 1: Direct Property Setting

Set properties directly on entities without creating assertions:

persons:
  person-alice-chen:
    properties:
      name:
        value: "Alice Chen"
        fields:
          given: "Alice"
          surname: "Chen"
      occupation: "software engineer"

events:
  event-alice-birth:
    type: birth
    date: "1985-06-15"
    place: place-boston
    participants:
      - person: person-alice-chen
        role: subject

Best for:

• Initial data entry from family records
• Quick capture (document evidence later)
• Personal research with trusted sources
• Early stages before formal research begins

Limitations:

• No documented evidence chain
• Hard to verify conclusions later
• Doesn't capture conflicting evidence

Approach 2: Assertion-Backed Properties

Create assertions that document evidence for each property value:

# First, create a birth event for the person
events:
  event-robert-birth:
    type: birth
    date: "1955-03-22"
    place: place-new-york
    participants:
      - person: person-robert-chen
        role: subject

# Then, create an assertion documenting the evidence
assertions:
  assertion-robert-birth:
    subject:
      event: event-robert-birth
    property: date
    value: "1955-03-22"
    citations:
      - citation-robert-birth-cert
    confidence: high
    status: proven
    notes: "Primary source: original birth certificate"

Best for:

• Professional genealogy research
• Documenting conflicting evidence
• Collaborative research projects
• Building verifiable research trails

The Evidence Chain

Complete evidence documentation follows this pattern:

Repository → Source → Citation → Assertion ─┬─→ Property (e.g. name, occupation)
    ↓          ↓          ↓          ↓      │
 Archives   Records   Specific   Evidence-  │
            & Docs    Reference  Based      └─→ Event (e.g. date, place)
                                 Claim

Example chain in this archive:

1. Repository: repository-nyc-records (NYC Department of Records)
2. Source: source-nyc-birth-records (NYC Birth Certificates)
3. Citation: citation-robert-birth-cert (specific certificate reference)
4. Assertion: assertion-robert-birth (claim that Robert was born March 22, 1955)
5. Event: event-robert-birth with date "1955-03-22" and place place-new-york

Learn More: The evidence chain supports the Genealogical Proof Standard (GPS), which requires (1) reasonably exhaustive research, (2) complete source citations, (3) analysis of evidence, (4) resolution of conflicts, and (5) a soundly reasoned conclusion. GLX's assertion model provides the data structure for documenting all five elements. See ADR-0002: Evidence-first data model for the rationale.

Recommended Workflow

For Quick Data Entry

1. Create person with properties directly
2. Add a note indicating source isn't documented
3. Return later to add assertions with evidence

events:
  event-alice-birth:
    type: birth
    date: "1985-06-15"
    place: place-boston
    participants:
      - person: person-alice-chen
        role: subject
    notes: |
      Quick entry from family records.
      TODO: Add source citations when time permits.

For Rigorous Research

1. Create sources and repositories first
2. Add citations referencing specific evidence
3. Create assertions linking citations to claims
4. Set properties based on assertion conclusions

Iterative Approach (Best Practice)

Start with direct properties, then add evidence chain incrementally:

1. Day 1: Quick data entry with properties
2. Week 2: Add source for key documents
3. Month 3: Create citations for specific references
4. Ongoing: Build assertions as you research

Confidence vs Status

Assertions have two independent fields for tracking certainty and verification:

• confidence — how certain you are about the claim (high, medium, low)
• status — the research state of the assertion (proven, speculative, disputed, disproven, unresearched)

A confidence: high + status: speculative assertion means "I'm fairly sure this is right, but I haven't verified it yet."

Properties vs Assertions: Key Differences

Aspect	Properties Only	With Assertions
Speed	Fast	Slower
Evidence	Implicit	Explicit
Verification	Difficult	Easy
Conflicts	Hidden	Documented
Collaboration	Limited	Excellent
Audit Trail	None	Complete

Existential Assertions

An assertion with neither property nor participant is an existential assertion — it simply says "this entity is evidenced by these sources." This is the minimum useful assertion, and is especially helpful for relationships and events where you want to document existence without claiming any specific property value.

relationships:
  rel-robert-alice-parent-child:
    type: parent_child
    participants:
      - person: person-robert-chen
        role: parent
      - person: person-alice-chen
        role: child

assertions:
  assertion-robert-alice-parentage:
    subject:
      relationship: rel-robert-alice-parent-child
    date: "1990"
    citations:
      - citation-1990-census-chen
    confidence: high
    notes: "1990 census lists Robert Chen as head of household with Alice Chen (age 5) as daughter"

Adding date makes it temporal: "this relationship existed in 1990." Without date, the assertion simply says the relationship is evidenced by the source, with no temporal scope.

When to use existential assertions:

• Relationships — evidencing a parent-child or marriage without asserting a specific property
• Events — confirming an event occurred without asserting its date or place yet
• Places — documenting that a place existed at a given time

Multiple Evidence for Same Property

Assertions can corroborate each other:

assertions:
  assertion-robert-financial-advisor:
    subject:
      person: person-robert-chen
    property: occupation
    value: "financial advisor"
    citations:
      - citation-2000-census-chen    # Census record
      - citation-linkedin-career      # LinkedIn profile
    confidence: high
    notes: "Multiple sources confirm career change in 1995"

Conflicting Evidence (and Its Resolution)

Corroboration is the easy case. The harder — and more important — case is when sources disagree. Record each claim as its own assertion on the same property, then resolve the conflict by marking which claim the evidence supports. This keeps disagreements visible instead of silently overwriting one value with another, and it is exactly what the Genealogical Proof Standard means by resolution of conflicting evidence.

In this archive, two sources conflict on Robert's birth year: his birth certificate says 1955, but family oral history (cousin Sarah) remembers him as a "1956 baby." Both claims are recorded as separate assertions on event-robert-birth's date property, then resolved in favor of the primary source:

assertions:
  # Winning assertion — primary source resolves the conflict
  assertion-robert-birth:
    subject:
      event: event-robert-birth
    property: date
    value: "1955-03-22"
    citations: [citation-robert-birth-cert]
    confidence: high
    status: proven
    notes: "Birth certificate takes precedence over the 1956 recollection."

  # Conflicting assertion — secondary source, contradicted by the certificate
  assertion-robert-birth-lore:
    subject:
      event: event-robert-birth
    property: date
    value: "1956"
    citations: [citation-robert-birth-lore]
    confidence: low
    status: disproven
    notes: "Family recollection; contradicted by the birth certificate."

Both assertions point at the same property of the same event but carry different values — that is what makes this a conflict rather than corroboration. The status field records the outcome of the analysis:

• status: proven — the claim survived analysis (here, backed by a primary source)
• status: disproven — evidence was found that contradicts the claim
• status: disputed — sources conflict and the resolution is still unclear

Not yet resolved? If you have analyzed the conflict but cannot yet decide, leave both competing assertions in place, or record a single assertion citing the conflicting sources with status: disputed. Reserve proven/disproven for conflicts you have actually resolved. See Assertion Entity — status for the full pattern.

Temporal Properties with Assertions

For properties that change over time, create separate assertions for each time period:

persons:
  person-robert-chen:
    properties:
      occupation:
        - value: "accountant"
          date: "FROM 1978 TO 1995"
        - value: "financial advisor"
          date: "FROM 1995 TO 2020"

assertions:
  assertion-robert-accountant:
    subject:
      person: person-robert-chen
    property: occupation
    value: "accountant"
    citations: [citation-1990-census-chen]

  assertion-robert-financial-advisor:
    subject:
      person: person-robert-chen
    property: occupation
    value: "financial advisor"
    citations: [citation-2000-census-chen, citation-linkedin-career]

Files in This Example

• archive.glx - Single-file archive demonstrating both approaches
• README.md - This documentation

See Also

• Temporal Properties Example - Detailed temporal value patterns
• Complete Family Example - Full multi-file archive structure
• Participant Assertions Example - Evidencing who participated in an event
• Core Concepts - Assertion-Aware Data Model
• Assertion Entity - Existential Assertions