MAXGEN schema · v1.13
MaxName
One name, every form it has ever taken, with sources.
Download MaxName v1.13
All versions
https://opengenealogyai.org/schemas/maxgen/v1/name.schema.json
Why Maxwell and Makeswell are the same family
Search a Scottish record set for "Maxwell" and you will not find Makeswell, Maccuswell, M'Axwell, McAxwell or Maxwel, though every one of them is the same name written by a different clerk in a different decade. The problem is bigger than spelling. Ó Briain became O'Brien when colonial administrators wrote it down. Müller became Miller on the far side of the Atlantic. Yochanan became Iohannes became Jean became John became Ivan.
No open standard captured this before. We checked GEDCOM X, WeRelate, Behind the Name, JRC-Names, the Library of Congress name authority, VIAF, schema.org, HistNorm and Popolo. None records typed, directed, sourced name relationships across languages, scripts, places and centuries. MaxName fills that gap.
What it is
One MaxName record is one canonical form (the modern reference spelling) plus everything known about how that name has been written and adapted.
regional_canonical[]: the preferred form in other communities. "John" carries Seán, Eoin, Ioan, Johann. None is more real than another.variants[]: every known form, each with its own UUID (so it can be cited or retracted on its own), the text exactly as it appears in records, a type (spelling variant, nickname, anglicisation, latinisation, abbreviation, scribal corruption, phonetic rendering, emigration adaptation, translation, patronymic form, legal substitution…), its scope (place, language, script, period), a frequency (rare, occasional, common, dominant), an attestation source, a confidence, anddisputed_by[]for scholars who disagree.cognates[]: links to other MaxName records across languages, with a relationship type (etymological root, cross-language cognate, derivative, contracted form) and a direction: Maxwell derives from Maccus; John and Ivan are parallel cognates of Iohannes. Every link cites its source.phonetic_keys{}: pre-computed codes for fuzzy search under six algorithms (Soundex, NYSIIS, Metaphone, Double Metaphone, Daitch-Mokotoff, Beider-Morse), each with its algorithm version so a code computed in 2026 can be reconciled with one computed in 2040.
Two-pass cognates (new in v1.13)
Cognate relationships are discovered while researching the first name, before a record for the second exists. A cognate may therefore be recorded unresolved, carrying only related_canonical_form ("John"), and later resolved by a linking pass that adds the related_name_id. Both states are valid; a cognate pointing at nothing is not.
The Maxwell example
Canonical form Maxwell, a surname of Old Norse origin: Maccus's pool, first attested about 1144. Variants: Maccuswell (Latin charters, 1144 to 1300, dominant), Makeswell (Scots parish registers, 1600 to 1750, occasional), M'Axwell (an abbreviation, 1700s to 1800s), McAxwell (Virginia colonial records, rare, with one scholar disputing whether it is corruption or anglicisation). Phonetic keys Soundex M240, Daitch-Mokotoff 645400. One cognate: derives from Maccus, citing Reaney's Dictionary of English Surnames. With that record, a search for Makeswell finds Maxwell, and a transcription of Maccuswell from a twelfth-century charter lands in the right family.
Variant types
Fields
| Field | Type | Meaning |
|---|---|---|
name_id required | string | Globally unique identifier for this name record. |
schema_version required | const "1.13" | MAXGEN lockstep version. |
canonical_form required | string | The modern authoritative spelling of this name — the form used as the anchor for all variants. |
canonical_script | enum | Writing system of canonical_form. |
regional_canonical | array of object | Language-specific preferred forms of this name for regions where the canonical_form is not the local preferred form. |
name_type required | enum | Structural category of this name. |
gender | enum | Gender association of this name in its canonical culture. |
language_of_origin | string | ISO 639-3 code of the language from which this name ultimately derives. |
etymology | string | Free-text explanation of the name's origins and meaning. |
see_also_urls | array of string | Links to authoritative external references — Behind the Name, Dictionary of the Scots Language, LCNAF authority record, Wiktionary etymology, etc. |
variants | array of object | All known variant forms of this name — spelling variants, nicknames, anglicizations, scribal corruptions, dialectal forms, and emigration adaptations. |
phonetic_keys | object | Pre-computed phonetic encodings of canonical_form for fuzzy search. |
cognates | array of object | Cross-language equivalents — names in other languages that are etymologically related to or culturally equivalent to this name. |
contributor | object | Who created or is responsible for this MaxName record overall — the person or system that established the canonical form and the initial variant set. |
redistribution_license | enum | License governing redistribution of this name record. |
extensions | object | Product/implementation-specific fields. |
Example
Seán, the Irish form of John, with an anglicisation, an older spelling, and an unresolved cognate link.
{
"name_id": "e1f2a3b4-c5d6-4789-9abc-de0123456789",
"schema_version": "1.13",
"canonical_form": "Seán",
"canonical_script": "latin",
"name_type": "given",
"gender": "masculine",
"language_of_origin": "sga",
"etymology": "Seán is the Irish form of John, borrowed from the Anglo-Norman Jehan rather than directly from the Latin Iohannes. Norman French speakers arriving in Ireland from the twelfth century brought Jehan with them; Irish speakers adapted it to their own sound system as Seán. The name therefore sits one step further along the chain than most European forms of John — it descends from a French intermediary, not from the Latin original, which is why it looks so unlike Johannes while meaning exactly the same thing.",
"regional_canonical": [
{
"form": "Seán",
"language": "ga",
"locale": "IE",
"notes": "Standard modern Irish spelling with the síneadh fada on the a."
},
{
"form": "Eoin",
"language": "ga",
"locale": "IE",
"notes": "A separate Irish form of John taken directly from the Latin Iohannes rather than via Norman French. Eoin and Seán coexist in Irish; Eoin is conventionally used for the biblical John."
}
],
"variants": [
{
"variant_id": "f2a3b4c5-d6e7-4890-abcd-ef1234567890",
"variant_text": "Shane",
"variant_type": "anglicization",
"locale": "IE",
"language": "en",
"script": "latin",
"period_start": 1600,
"frequency": "common",
"attestation_source": "Ó Corráin & Maguire, Irish Names (1981), entry for Seán.",
"notes": "Phonetic English respelling of Seán, which later became an independent given name in its own right in the anglophone world.",
"confidence": 0.97
},
{
"variant_id": "a3b4c5d6-e7f8-4901-bcde-f01234567891",
"variant_text": "Seaán",
"variant_type": "spelling_variant",
"locale": "IE",
"language": "ga",
"script": "latin",
"period_start": 1400,
"period_end": 1900,
"frequency": "occasional",
"attestation_source": "Ó Corráin & Maguire, Irish Names (1981), entry for Seán.",
"notes": "Older Irish orthography, superseded by the modern standardised spelling.",
"confidence": 0.93
}
],
"phonetic_keys": {
"soundex": {
"value": "S500",
"algorithm_version": "american-1918"
},
"metaphone": {
"value": "SN",
"algorithm_version": "jellyfish-1.x"
}
},
"cognates": [
{
"cognate_id": "b4c5d6e7-f8a9-4012-cdef-012345678902",
"related_canonical_form": "John",
"relationship_type": "cross_language_cognate",
"direction": "parallel_cognate",
"attestation_source": "Ó Corráin & Maguire, Irish Names (1981); Withycombe, Oxford Dictionary of English Christian Names (3rd ed. 1977).",
"notes": "MAXGEN v1.13 UNRESOLVED COGNATE — this link was recorded during first-pass research, before a MaxName record for 'John' existed. It carries related_canonical_form but no related_name_id, which the schema permits from v1.13 onward. A later linking pass resolves the UUID. Under v1.12 this fact could not be stored at all and would have been discarded.",
"contributor": {
"contributor_type": "ai",
"contributor_id": "maxname-worker-1",
"asserted_at": "2026-08-14T00:00:00Z"
}
},
{
"cognate_id": "c5d6e7f8-a9b0-4123-def0-123456789013",
"related_canonical_form": "Jehan",
"relationship_type": "etymological_root",
"direction": "this_derives_from",
"attestation_source": "Ó Corráin & Maguire, Irish Names (1981), entry for Seán.",
"notes": "Anglo-Norman intermediary. Also unresolved — recorded by canonical form only.",
"contributor": {
"contributor_type": "ai",
"contributor_id": "maxname-worker-1",
"asserted_at": "2026-08-14T00:00:00Z"
}
},
{
"cognate_id": "d6e7f8a9-b0c1-4234-ef01-234567890124",
"related_name_id": "a1b2c3d4-e5f6-4789-abcd-ef0123456789",
"related_canonical_form": "Eoin",
"relationship_type": "cross_language_cognate",
"direction": "parallel_cognate",
"attestation_source": "Ó Corráin & Maguire, Irish Names (1981).",
"notes": "RESOLVED COGNATE — carries both the UUID and the readable form. This is the end state a linking pass produces.",
"contributor": {
"contributor_type": "ai",
"contributor_id": "maxname-linker",
"asserted_at": "2026-08-14T00:00:00Z"
}
}
],
"redistribution_license": "CC-BY",
"contributor": {
"contributor_type": "ai",
"contributor_id": "maxname-worker-1",
"asserted_at": "2026-08-14T00:00:00Z"
}
}
Listen
MaxName — Why Maxwell and Makeswell are the same family
23:31Variants, cognates, phonetic keys, and the council design process behind the newest schema.