Entities, events, relations

A Document Logical Unit is not just a wrapper around its pages. Once a DLU exists as a coherent document, archAIc reads it as a whole and lifts a property graph out of the text: the persons named in it, the places mentioned, the organisations involved, the events that took place, and the relationships between all of them. That graph is the catalogue record the institution actually wants. It is what turns a searchable archive into a research dataset.

The four object kinds

Every DLU carries four kinds of extracted record.

Persons. Anyone named in the document, with a role inside the document (testador, alcalde, padre, padrino, escribano, testigo, comparecente), the attributes mentioned in the text (profession, civil status, age, residence), and the line references where each mention appears. A person who appears three times across four pages keeps all three references, not just the first.

Places. Towns, parishes, streets, properties, landmarks, regions. Each with a role within the document (residence, birthplace, transaction location, parish of record), the coordinates if geocoded, and the line references where the place is named.

Organisations. Parishes, confraternities, guilds, councils, courts, commissions, ministries. Same shape as persons and places: a surface form, an optional canonical, an optional cross-DLU id, a role, line references.

Events. What happened: a birth, a marriage, a death, a land transfer, a vote, an election, a lawsuit. Each event is typed under CIDOC-CRM (E5 Event, E7 Activity, E67 Beginning of Existence, E69 Death, E10 Transfer of Custody, E9 Move, and the rest of the relevant CRM classes), and each event carries its participants (with their roles), its location, its date, any monetary amounts, and the line references that support the claim.

Relationships connect any of the above: (X) -[married_to]-> (Y) in a matrimonio, (X) -[inherited_from]-> (Y) in a testamento, (X) -[witnessed]-> (Y) in a contract, (X) -[alcalde_of]-> (Place) in an acta, (X) -[baptized_in]-> (Parish) in a parish book. Each edge carries the DLU it was extracted from, its line references, an optional qualifier (“before witnesses X and Y”), and its own review state.

All of this is typed under CIDOC-CRM. The catalogue does not need to invent its own ontology to plug into the wider linked-data world: an export emits CRM classes directly, and a downstream consumer (a discovery portal, a research agent, a linked-data triplestore) reads them without translation.

Three layers of identity

Old records have a problem the modern world mostly does not: the same person is named ten different ways across ten documents. Don Emilio Romay Mosquera, Don Emilio Romay, D. E. Romay, Romay, sometimes simply el alcalde. The handwriting varies, the abbreviations vary, the deference varies, and the same person may be referenced in dozens of acts over thirty years of council books.

archAIc keeps three identity fields on every entity (person, place, organisation, and on event location and event participants):

• surface_form: the literal ink, exactly as the text wrote it. “Don Emyl. Romai”. Always populated. Used for verbatim quoting and for showing the curator what the page actually says.
• canonical: the normalised form for this DLU. “Emilio Romay”. May be null when the system has not yet produced one. Used for in-DLU deduplication. Three mentions of the same person inside one document collapse on canonical.
• entity_id: the cross-DLU authority id. The id that says “this is the same Don Emilio that appears in DLUs 47, 312, and 1908.” Today this is mostly null. The promotion from canonical (DLU-local) to entity_id (corpus-wide) is a deliberate curatorial decision. The cataloguer reviews twenty draft mentions across twenty documents and confirms that yes, they refer to the same real-world person. From that moment, every old mention is linked to the same authority record, and every new document mentioning the same name is automatically attached.

Two rows with matching canonical and entity_id: null are probably the same entity. archAIc has not yet formally said so. The hedge is real and is what the cataloguer is paid to remove.

The same model applies symmetrically to places (places.entity_id resolves to a corpus-wide place), organisations, event locations, and event participants. Relationships carry subject_entity_id and object_entity_id on the same scheme.

Authority-file linkage

When a canonical entity is promoted to a cross-DLU authority record, it can be linked outward to standard authority files. Places resolve against GeoNames and the Getty Thesaurus of Geographic Names (TGN); persons resolve against EAC-CPF records emitted by the institution or by its national authority. The linkage is optional and the system functions without it, but once an entity carries a GeoNames id or a TGN id, downstream consumers (a discovery portal, a research agent, a map service) can dereference it against the wider open-data ecosystem.

For places this also unlocks the map view: a DLU’s geocoded places become pins, the corpus’s places become a heatmap with a time slider, and a person who appears in multiple located events becomes a trajectory on the map. None of which is a separate ingest. It is the same places.entity_id, dereferenced against the same gazetteer.

Mentions: the anchor that makes the graph trustworthy

Every entity, every event, and every relationship carries at least one mention: a (page, line) reference (often with character offsets inside the line) pointing at the ink that justified the claim. A person extracted from a DLU does not just say “Don Emilio Romay was here.” It says “Don Emilio Romay was here, see page 22, line 10, with anchor confidence 0.76, surface form Don Emyl. Romai.” The cataloguer clicks the claim, the page image opens with that line highlighted, and the evidence is one glance away.

This is enforced at write time and at read time. See No anchor, no entry for the full rule.

The mentions also feed the UI’s visual conventions. The drawer that summarises a DLU’s extracted graph uses a three-colour code: persons in orange, places in blue, events in gold. The same palette runs across the focal-graph view, the timeline, the map, the cross-DLU browser, and the IIIF overlays. A cataloguer learns the convention once and reads it everywhere.

Review state, change log, training corpus

Every extracted record starts in a pending_review state. The cataloguer confirms, edits, rejects, merges, or splits. Each transition is recorded in a change log. The aggregate of those transitions is not just an audit trail. It is the evaluation corpus the system trains the next round of extraction against, and the dataset that proves to a grant funder or a board of trustees that the catalogue is actually being curated, not just generated.

Confirmed entities and events are eligible for export, for cross-DLU rollup, for inclusion in the corpus-wide authority pool. Pending or rejected records are not. A consumer that reads from archAIc through the MCP server, the REST API, or an export package sees only the curated layer by default, with explicit opt-in to see pending work. The institution decides what is published and what stays inside the curation workbench.