MaxPerson

You cannot ask the dead who they are

Genealogy reconstructs people from fragments: names written by clerks who may have misspelled them, ages self-reported to a census taker, dates in calendars that no longer match ours. Most file formats can hold only one answer per fact, so the uncertainty has to be resolved before it can be saved: one John Maxwell, one father, and the doubt lives in a notebook instead of the data.

MaxPerson keeps the uncertainty in the data, where software and researchers can work with it.

What it is

A MaxPerson is a probable identity: a bundle of assertions, each saying this source claims this, with this confidence, recorded by this agent on this date. There are no bare facts in a MaxPerson. There are only assertions with evidence behind them.

• name_assertions[]: every name this person was called, including the misspellings, each with its source.
• birth_assertions[] and death_assertions[]: date ranges and places, one per source.
• parent_assertions[] and child_assertions[]: several candidates are normal. A probable father at 0.75 and a possible father at 0.35 both stay in the record. The tree shows the likelier one; nothing is erased.
• spouse_assertions[]: marriages with type, dates, place and how they ended. Kept in both spouses' records.
• event_assertions[]: everything between the bookends: immigration, residence, military service, probate, burial. Event types map to GEDCOM tags.
• external_id_assertions[]: scored links to the same person on FamilySearch, WikiTree, Find a Grave and others. Scored, not merged, because those databases contain duplicates too.
• dna_evidence[]: DNA matches that touch this person as a candidate common ancestor, feeding the overall confidence.

Composite confidence

composite_confidence is one number, 0 to 1, for how sure we are about the identity as a whole. It is computed from all the assertions, weighted by source quality, using a "noisy-OR" combination (two independent sources agreeing raise confidence more than either alone, but not as if they were certain). Because every assertion cites a source_record_id, the engine can notice when two assertions really come from the same underlying document and avoid double-counting.

The merge model

When evidence shows two MaxPerson records are the same individual, one absorbs the other. merge_history[] records the confidence, method, signals, who merged and when. The absorbed record stays, marked merge_status: merged_away. If later evidence shows they were different people after all, the merge is reversed on the same quality of evidence that made it.

Privacy

is_living: true locks the record. Public endpoints return "not found". The record still exists internally and can be researched, but it is never exposed. Linked DNA records inherit the same lock. This is a design requirement of the standard, not a policy any implementation can switch off.

Fields

Example

Mary Todd Lincoln as a MaxPerson: two names (birth and married), an exact birth and death, one marriage, every claim citing the same marriage record.

{
  "person_id": "b1000000-0006-4000-8000-000000000006",
  "schema_version": "1.13",
  "is_living": false,
  "composite_confidence": 0.95,
  "name_assertions": [
    {
      "name_as_written": "Mary Todd",
      "given_name": "Mary",
      "surname": "Todd",
      "name_type": "birth",
      "confidence": 0.95,
      "source_record_id": "a1b2c3d4-0003-4000-8000-000000000003",
      "asserted_by": "extractor-agent-haiku-001",
      "asserted_at": "2026-05-01T14:00:00Z"
    },
    {
      "name_as_written": "Mary Lincoln",
      "given_name": "Mary",
      "surname": "Lincoln",
      "name_type": "married",
      "confidence": 0.99,
      "source_record_id": "a1b2c3d4-0003-4000-8000-000000000003",
      "asserted_by": "extractor-agent-haiku-001",
      "asserted_at": "2026-05-01T14:00:00Z"
    }
  ],
  "birth_assertions": [
    {
      "year_min": 1818,
      "year_max": 1818,
      "month": 12,
      "day": 13,
      "date_type": "exact",
      "place_as_written": "Lexington, Kentucky",
      "country_code": "US",
      "confidence": 0.98,
      "source_record_id": "a1b2c3d4-0003-4000-8000-000000000003",
      "asserted_by": "extractor-agent-haiku-001",
      "asserted_at": "2026-05-01T14:00:00Z"
    }
  ],
  "death_assertions": [
    {
      "year_min": 1882,
      "year_max": 1882,
      "month": 7,
      "day": 16,
      "date_type": "exact",
      "place_as_written": "Springfield, Illinois",
      "country_code": "US",
      "confidence": 0.99,
      "source_record_id": "a1b2c3d4-0003-4000-8000-000000000003",
      "asserted_by": "extractor-agent-haiku-001",
      "asserted_at": "2026-05-01T14:00:00Z"
    }
  ],
  "spouse_assertions": [
    {
      "spouse_person_id": "b1000000-0007-4000-8000-000000000007",
      "marriage_year_min": 1842,
      "marriage_year_max": 1842,
      "confidence": 0.99,
      "source_record_id": "a1b2c3d4-0003-4000-8000-000000000003",
      "asserted_by": "extractor-agent-haiku-001",
      "asserted_at": "2026-05-01T14:00:00Z"
    }
  ],
  "source_record_ids": [
    "a1b2c3d4-0003-4000-8000-000000000003"
  ],
  "redistribution_license": "public-domain",
  "asserted_by": "extractor-agent-haiku-001",
  "asserted_at": "2026-05-01T14:00:00Z",
  "judge_approved": true,
  "judge_approved_at": "2026-05-04T09:00:00Z"
}

Listen

← All seven schemas