Skip to content

Instantly share code, notes, and snippets.

@johnmyleswhite

johnmyleswhite/claims-extraction-prompt.md

Created January 6, 2026 14:46
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save johnmyleswhite/227fe9e24275792cd12d115d0400fa65 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save johnmyleswhite/227fe9e24275792cd12d115d0400fa65 to your computer and use it in GitHub Desktop.
Download ZIP
Claims extraction prompt for genealogy
Raw
claims-extraction-prompt.md

Claims Extraction Prompt for Claude Code

When analyzing genealogical source documents (images, PDFs, or text files), extract factual claims and output them in the claims.json format described below.

Output Format

Create a JSON file with this structure:

{
  "claims": [
    {
      "main_person": "Full Name As Written",
      "fact": {
        "type": "FactType",
        // ... fact-specific fields
      },
      "confidence": "Low" | "Medium" | "High"
    }
  ]
}

Fact Types

Extract facts using these exact type names and field structures:

Birth Facts

{"type": "BornOnDate", "date": <PartialDate>}
{"type": "BornAtPlace", "place": "Location string"}

Death Facts

{"type": "DiedOnDate", "date": <PartialDate>}
{"type": "DiedAtPlace", "place": "Location string"}

Residence Facts

{"type": "LivedAt", "date": <PartialDate or null>, "place": "Address"}

Use LivedAt for any evidence that a person resided at a location. The date is optional - include it if the document specifies when they lived there.

Age Facts

{"type": "AgeOnDate", "date": <PartialDate>, "age": <integer>}

Use when a document states someone's age at a specific time (e.g., census records). The date is required.

Relationship Facts

{"type": "FatherIsOtherPerson", "other_person": "Father's Name"}
{"type": "MotherIsOtherPerson", "other_person": "Mother's Name"}
{"type": "MarriedToOtherPerson", "other_person": "Spouse's Name"}
{"type": "SisterIsOtherPerson", "other_person": "Sister's Name"}
{"type": "BrotherIsOtherPerson", "other_person": "Brother's Name"}
{"type": "GodfatherIsOtherPerson", "other_person": "Godfather's Name"}
{"type": "GodmotherIsOtherPerson", "other_person": "Godmother's Name"}

Marriage Facts

{"type": "MarriedOnDate", "date": <PartialDate>, "other_person": "Spouse Name" or null}
{"type": "MarriedAtPlace", "place": "Location"}

Baptism Facts

{"type": "BaptizedOnDate", "date": <PartialDate>}
{"type": "BaptizedAtPlace", "place": "Location"}
{"type": "BaptismPriestWas", "priest": "Priest's Name"}

Use for baptismal records. The priest field records the name of the officiating priest as written in the document.

Work Facts

{"type": "WorkedAs", "date": <PartialDate or null>, "job": "Occupation"}

Immigration Facts

{"type": "ImmigratedOnDate", "date": <PartialDate>}
{"type": "ImmigratedToPlace", "place": "Destination"}
{"type": "ImmigratedFromPlace", "place": "Origin"}

Citizenship Facts

{"type": "BecomeCitizenOnDate", "date": <PartialDate>}

PartialDate Format

Dates use this structure to handle partial/uncertain information:

{
  "raw": "Original text from document",
  "year": {"Known": 1912} or {"Unknown": null},
  "month": {"Known": 10} or {"Unknown": null},
  "day": {"Known": 17} or {"Unknown": null},
  "uncertain": false
}
  • raw: Preserve the exact date string as written in the document
  • year/month/day: Use {"Known": value} if known, {"Unknown": null} if not
  • uncertain: Set to true if the document indicates uncertainty (e.g., "about 1857", "circa 1920", "?")

Date Examples

Full date: "October 17, 1912"

{
  "raw": "October 17, 1912",
  "year": {"Known": 1912},
  "month": {"Known": 10},
  "day": {"Known": 17},
  "uncertain": false
}

Year only: "1920"

{
  "raw": "1920",
  "year": {"Known": 1920},
  "month": {"Unknown": null},
  "day": {"Unknown": null},
  "uncertain": false
}

Uncertain date: "about 1857"

{
  "raw": "about 1857",
  "year": {"Known": 1857},
  "month": {"Unknown": null},
  "day": {"Unknown": null},
  "uncertain": true
}

Confidence Levels

Assign confidence based on:

  • High: Direct statement in official document (birth certificate, death certificate, marriage record)
  • Medium: Indirect evidence or secondary source (census record, city directory, obituary)
  • Low: Inferred information, unclear handwriting, or questionable source

Extraction Guidelines

1. Extract Every Distinct Fact

Each piece of information becomes a separate claim. A birth certificate might yield:

  • BornOnDate
  • BornAtPlace
  • FatherIsOtherPerson
  • MotherIsOtherPerson
  • Multiple LivedAt facts (for parents' residence)

A baptismal record might yield:

  • BaptizedOnDate
  • BaptizedAtPlace
  • BaptismPriestWas
  • GodfatherIsOtherPerson
  • GodmotherIsOtherPerson
  • FatherIsOtherPerson
  • MotherIsOtherPerson

2. Use Names As Written

Record names exactly as they appear in the document. Don't normalize or correct spelling:

  • "Jno" stays as "Jno" (not "John")
  • "Margt" stays as "Margt" (not "Margaret")

3. One Claim Per Person Per Fact

If a census shows 5 people living at an address, create 5 separate LivedAt claims, one for each person.

4. Handle Census Records Systematically

For each person listed in a census, extract:

  • LivedAt (address + census date)
  • AgeOnDate (census date + stated age)
  • BornAtPlace (if birthplace column exists)
  • Relationship facts (head of household relationships)
  • WorkedAs (if occupation column exists)

5. Handle Tabular Vital Records Registers

Birth and death registers often contain many entries per page. When extracting from these:

  1. Use folder context to identify the target person - The folder name (e.g., "Agnes Mary White - 1913") indicates who you're looking for
  2. Carefully locate the correct row - Scan for the matching name before reading any details
  3. Read across the entire row - These registers have many narrow columns; ensure you're reading data from the same row throughout
  4. Common columns in birth registers:
    • Date of birth (often just month/day, with year from page header)
    • Child's name
    • Sex
    • Place of birth (may be hospital or home address)
    • Parents' residence
    • Father's name and occupation
    • Mother's maiden name
    • Parents' birthplaces

6. Distinguish Index Documents from Source Records

Birth/death indexes are finding aids, not primary records:

  • The "Town" column in an index often indicates where the record is filed, not where the event occurred
  • Index documents provide: name, year, volume/page reference
  • Do NOT extract place of birth from an index's "Town" column
  • If you have both an index and the actual record, prefer the detailed record for all facts except confirming the person exists
  • Index documents warrant Medium confidence for dates, but should not be used for place claims

7. Preserve Ambiguity

If information is unclear:

  • Use lower confidence
  • Include what you can read in the raw field
  • Mark uncertain dates with "uncertain": true

Example: Census Record Extraction

Given a 1920 US Census showing:

Address: 125 Eutaw St, Boston
Head: John White, age 32, born Massachusetts, occupation: Clerk
Wife: Mary White, age 28, born Ireland
Son: Thomas White, age 5, born Massachusetts

Output:

{
  "claims": [
    {
      "main_person": "John White",
      "fact": {"type": "LivedAt", "date": {"raw": "1920", "year": {"Known": 1920}, "month": {"Unknown": null}, "day": {"Unknown": null}, "uncertain": false}, "place": "125 Eutaw St, Boston"},
      "confidence": "Medium"
    },
    {
      "main_person": "John White",
      "fact": {"type": "AgeOnDate", "date": {"raw": "1920", "year": {"Known": 1920}, "month": {"Unknown": null}, "day": {"Unknown": null}, "uncertain": false}, "age": 32},
      "confidence": "Medium"
    },
    {
      "main_person": "John White",
      "fact": {"type": "BornAtPlace", "place": "Massachusetts"},
      "confidence": "Medium"
    },
    {
      "main_person": "John White",
      "fact": {"type": "WorkedAs", "date": {"raw": "1920", "year": {"Known": 1920}, "month": {"Unknown": null}, "day": {"Unknown": null}, "uncertain": false}, "job": "Clerk"},
      "confidence": "Medium"
    },
    {
      "main_person": "John White",
      "fact": {"type": "MarriedToOtherPerson", "other_person": "Mary White"},
      "confidence": "Medium"
    },
    {
      "main_person": "Mary White",
      "fact": {"type": "LivedAt", "date": {"raw": "1920", "year": {"Known": 1920}, "month": {"Unknown": null}, "day": {"Unknown": null}, "uncertain": false}, "place": "125 Eutaw St, Boston"},
      "confidence": "Medium"
    },
    {
      "main_person": "Mary White",
      "fact": {"type": "AgeOnDate", "date": {"raw": "1920", "year": {"Known": 1920}, "month": {"Unknown": null}, "day": {"Unknown": null}, "uncertain": false}, "age": 28},
      "confidence": "Medium"
    },
    {
      "main_person": "Mary White",
      "fact": {"type": "BornAtPlace", "place": "Ireland"},
      "confidence": "Medium"
    },
    {
      "main_person": "Mary White",
      "fact": {"type": "MarriedToOtherPerson", "other_person": "John White"},
      "confidence": "Medium"
    },
    {
      "main_person": "Thomas White",
      "fact": {"type": "LivedAt", "date": {"raw": "1920", "year": {"Known": 1920}, "month": {"Unknown": null}, "day": {"Unknown": null}, "uncertain": false}, "place": "125 Eutaw St, Boston"},
      "confidence": "Medium"
    },
    {
      "main_person": "Thomas White",
      "fact": {"type": "AgeOnDate", "date": {"raw": "1920", "year": {"Known": 1920}, "month": {"Unknown": null}, "day": {"Unknown": null}, "uncertain": false}, "age": 5},
      "confidence": "Medium"
    },
    {
      "main_person": "Thomas White",
      "fact": {"type": "BornAtPlace", "place": "Massachusetts"},
      "confidence": "Medium"
    },
    {
      "main_person": "Thomas White",
      "fact": {"type": "FatherIsOtherPerson", "other_person": "John White"},
      "confidence": "Medium"
    },
    {
      "main_person": "Thomas White",
      "fact": {"type": "MotherIsOtherPerson", "other_person": "Mary White"},
      "confidence": "Medium"
    }
  ]
}

Example: Birth Certificate Extraction

Given a birth certificate stating:

Name: John Maurice White
Date of Birth: October 17, 1912
Place of Birth: 409 Main St, Boston, MA
Father: Fergus J White, occupation: Plumber, birthplace: Boston
Mother: Mary S Barrett, birthplace: Cape Breton

Output:

{
  "claims": [
    {
      "main_person": "John Maurice White",
      "fact": {"type": "BornOnDate", "date": {"raw": "October 17, 1912", "year": {"Known": 1912}, "month": {"Known": 10}, "day": {"Known": 17}, "uncertain": false}},
      "confidence": "High"
    },
    {
      "main_person": "John Maurice White",
      "fact": {"type": "BornAtPlace", "place": "409 Main St, Boston, MA"},
      "confidence": "High"
    },
    {
      "main_person": "John Maurice White",
      "fact": {"type": "FatherIsOtherPerson", "other_person": "Fergus J White"},
      "confidence": "High"
    },
    {
      "main_person": "John Maurice White",
      "fact": {"type": "MotherIsOtherPerson", "other_person": "Mary S Barrett"},
      "confidence": "High"
    },
    {
      "main_person": "Fergus J White",
      "fact": {"type": "WorkedAs", "date": {"raw": "October 17, 1912", "year": {"Known": 1912}, "month": {"Known": 10}, "day": {"Known": 17}, "uncertain": false}, "job": "Plumber"},
      "confidence": "High"
    },
    {
      "main_person": "Fergus J White",
      "fact": {"type": "LivedAt", "date": {"raw": "October 17, 1912", "year": {"Known": 1912}, "month": {"Known": 10}, "day": {"Known": 17}, "uncertain": false}, "place": "409 Main St, Boston, MA"},
      "confidence": "High"
    },
    {
      "main_person": "Fergus J White",
      "fact": {"type": "BornAtPlace", "place": "Boston"},
      "confidence": "High"
    },
    {
      "main_person": "Mary S Barrett",
      "fact": {"type": "LivedAt", "date": {"raw": "October 17, 1912", "year": {"Known": 1912}, "month": {"Known": 10}, "day": {"Known": 17}, "uncertain": false}, "place": "409 Main St, Boston, MA"},
      "confidence": "High"
    },
    {
      "main_person": "Mary S Barrett",
      "fact": {"type": "BornAtPlace", "place": "Cape Breton"},
      "confidence": "High"
    }
  ]
}

Output Location

Save the claims file as a sidecar to the source document:

  • Source: People/John Morris White - 1912/Birth/Birth Record.jpg
  • Claims: People/John Morris White - 1912/Birth/Birth Record.jpg.claims.json

Validation Checklist

Before finalizing, verify:

  • Every fact type uses the exact field names specified above
  • All dates use the PartialDate structure with Known/Unknown wrappers
  • Names are recorded exactly as written in the document
  • Each person gets their own claims (don't combine people)
  • Confidence level is appropriate for the document type
  • The JSON is valid and properly formatted
  • For tabular documents, verified you are reading the correct row for the target person
  • For index documents, did NOT extract place of birth from the "Town" column
  • Extracted BornAtPlace facts for both parents when their birthplaces are listed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment