MAXGEN schema · v1.13

MaxSource

A catalogue of where records live, built for the question "where do I look next?"

Download MaxSource v1.13 All versions https://opengenealogyai.org/schemas/maxgen/v1/source.schema.json

The navigator's problem

A researcher needs the church records of a Lutheran family in Württemberg in the 1840s. If she knows German genealogy, she knows the answer: Archion and Matricula for the parish books, the state archive and Ancestry for emigration lists, the FamilySearch Research Wiki for which parishes cover which years. If she does not know, finding that out takes hours of catalogues, link directories, forum posts and emails.

MaxSource makes that knowledge machine-readable.

What it is

MaxSource is not a database of records. It is a database of where records live. One MaxSource record describes one source: its name and URL, what kind of thing it is, what it covers, how to get in, and how we came to know about it.

source_type: directory index, research wiki, record catalogue, record database, archive, DNA database, library, newspaper archive, forum, blog, society, other. The type decides how a system interacts with the source.
coverage{}: places (with country, state, county, town), record types, a time period as year_min / year_max, languages, and ethnic or religious groups. It answers queries like "everything covering Bavaria, death records, 1840 to 1870".
access{}: free web, paid subscription, API, bulk download, scrape-only, or on-site only; whether a login is needed; the API base URL; whether robots.txt allows crawling; and crawl notes that hold the etiquette robots.txt does not ("batch 50 items per call, five seconds between requests").
embedding_text: a natural-language description built for a vector database (a search index that matches meaning rather than exact words), so "Lutheran records in Württemberg in the 1840s" finds Archion even though no keyword matched.
provenance{}: which seed source found this, its status (active, dead link, superseded, unverified), who asserted it and when it was last verified. Dead links are marked, not deleted.
parent_source_id and coverage.record_count_estimate: sub-collections link to their parent, and an estimated record count is the primary ranking signal between a national index and a single parish page.

The copyright question

Some source catalogues are other people's curated work. MaxSource handles this with the licence field: an entry derived from a third-party directory is marked tier2-private and used internally for routing only. Openly licensed entries can be published. The standard makes the decision explicit and auditable; the operator makes the decision.

Source types

directory_index research_wiki record_catalog record_database archive dna_database library newspaper_archive forum blog society other

Fields

Field	Type	Meaning
`source_id` required	string	Globally unique identifier for this source entry.
`schema_version`	const "1.13"	MAXGEN version this record conforms to.
`parent_source_id`	string	MAXGEN v1.12 — UUID of the parent MaxSource record, when this entry is a sub-collection of a larger source.
`name` required	string	Human-readable name of the source, e.g.
`source_url` required	string	Canonical URL of the source or the specific category/page within it.
`source_type` required	enum	What KIND of source this is.
`redistribution_license` required	enum	Whether this source entry may be redistributed — same enum as MaxRecord.
`description`	string	Free-text summary of what this source holds and who it serves.
`embedding_text`	string	Denormalized natural-language text built from name + description + coverage, embedded into the vector DB so a query like 'German Lutheran parish records, Pomerania, early 1800s' retrieves this source.
`coverage`	object	What this source covers — drives 'where do I find X' matching.
`access`	object	How a harvester reaches the data — the politeness and method contract.
`provenance`	object	Where this entry came from and whether it is still good.
`extensions`	object	Product/implementation-specific fields live here, never in the core — e.g.

Example

A FamilySearch Research Wiki article catalogued as a public MaxSource.

{
  "source_id": "f1700000-0002-4000-8000-000000000002",
  "schema_version": "1.13",
  "name": "FamilySearch Research Wiki — Pomerania, Germany Genealogy",
  "source_url": "https://www.familysearch.org/en/wiki/Pomerania,_Germany_Genealogy",
  "source_type": "research_wiki",
  "redistribution_license": "CC-BY",
  "description": "FamilySearch Research Wiki locality article describing what records exist for Pomerania and where to find them. Openly licensed content, machine-readable via the MediaWiki API.",
  "embedding_text": "Pomerania Germany genealogy research: civil registration, Lutheran church books, census, emigration records; where Pomeranian records are held and how to access them.",
  "coverage": {
    "places": [
      {
        "place_as_written": "Pomerania, Germany",
        "country_code": "DE",
        "state_province": "Pomerania"
      }
    ],
    "record_types": [
      "parish_register",
      "census_row",
      "immigration_record",
      "land_deed"
    ],
    "time_period": {
      "year_min": 1650,
      "year_max": 1945
    },
    "languages": [
      "de",
      "la"
    ],
    "ethnic_or_religious_groups": [
      "Lutheran"
    ]
  },
  "access": {
    "access_method": "api",
    "requires_auth": false,
    "api_base_url": "https://www.familysearch.org/en/wiki/api.php",
    "robots_allowed": true,
    "crawl_notes": "Use MediaWiki api.php, batched up to 50 pages/call; pull locality + record-type articles only, not all 100k pages."
  },
  "provenance": {
    "discovered_via": "fs_research_wiki",
    "external_ref": "Pomerania, Germany Genealogy",
    "status": "active",
    "asserted_by": "source-crawler-agent-001",
    "asserted_at": "2026-06-25T17:05:00Z",
    "last_verified_at": "2026-06-25T17:05:00Z"
  },
  "extensions": {
    "harvester_adapter": "fs-wiki-adapter",
    "query_pattern": "by_place"
  }
}

Listen

Episode 5

MaxSource — The routing brain

18:16

Where records hide: coverage, access, provenance, and semantic search over sources.

Download MP3 · Study guide

← All seven schemas