1.1.3. Data Model¶

        erDiagram
%% Single edge collection connecting all entities
    ATTESTATION }o--|| EDGE : "attests_name, attests_geometry, attests_timespan"
    ATTESTATION }o--|| EDGE : "typed_by, sourced_by, relates_to, meta_attestation"
    EDGE }o--|| ATTESTATION : "subject_of, meta_attestation"
    SPATIAL_ENTITY }o--|| EDGE : "subject_of"
    SPATIAL_ENTITY ||--}o EDGE : "relates_to"
    AUTHORITY }o--|| EDGE : "part_of"
    AUTHORITY ||--}o EDGE : "typed_by, sourced_by, part_of"
    EDGE }o--|| NAME : "attests_name"
    EDGE }o--|| GEOMETRY : "attests_geometry"
    EDGE }o--|| TIMESPAN : "attests_timespan"


%% Single unified edge collection
    EDGE {
        string _key PK
        string _from "any collection/xyz"
        string _to "any collection/abc"
        string edge_type "subject_of, attests_name, attests_geometry, attests_timespan, relates_to, meta_attestation, typed_by, sourced_by, part_of"
        string meta_type "bundles, contradicts, supersedes, challenges, supports (for meta_attestations only)"
        json properties "flexible storage for edge-specific attributes"
        timestamp created
    }


%% Core entity collections (document collections - vertices/nodes)
    SPATIAL_ENTITY {
        string _key PK "ArangoDB key"
        string _id "things/xyz"
        text description
        string thing_type "location, historical_entity, collection, period, route, itinerary, network"
        string primary_name "denormalized from highest-certainty name attestation"
        point representative_point "denormalized from geometry for spatial indexing"
        timestamp created
        timestamp modified
    }
    NAME {
        string _key PK
        string _id "names/xyz"
        string name
        string language "ISO 639-3"
        string script "ISO 15924"
        array name_type "toponym, chrononym, ethnonym, odonym, hydronym"
        string ipa "International Phonetic Alphabet"
        string romanized "romanized/transliterated form"
        string transliteration_system "e.g., Pinyin, BGN/PCGN, ISO 259"
        vector embedding "REQUIRED: 256-dimensional vector for phonetic search"
    }
    TIMESPAN {
        string _key PK
        string _id "timespans/xyz"
        bigint start_earliest "Unix timestamp (milliseconds) or geological time"
        bigint start_latest "Unix timestamp (milliseconds)"
        bigint stop_earliest "Unix timestamp (milliseconds)"
        bigint stop_latest "Unix timestamp (milliseconds) or future sentinel"
        string label "human-readable period name"
        string precision "year, decade, century, era, geological_period"
        integer precision_value "numeric precision in years"
        string periodo_id "PeriodO URI for standard period definitions"
    }
    ATTESTATION {
        string _key PK
        string _id "attestations/xyz"
        integer sequence "for ordered sequences in routes/itineraries (nullable)"
        json connection_metadata "for networks: trade goods, flow direction, route_type"
        float certainty "0.0 to 1.0 (nullable if unknown)"
        text certainty_note "explanation of certainty assessment"
        text notes "additional context or commentary"
        timestamp created
        timestamp modified
    }
    GEOMETRY {
        string _key PK
        string _id "geometries/xyz"
        geometry geom "GeoJSON: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon"
        point representative_point "single point for spatial indexing and distance queries"
        geometry hull "convex hull for quick spatial filters"
        array bbox "[min_lon, min_lat, max_lon, max_lat]"
        array precision "e.g., [exact, approximate, uncertain, historical_approximate]"
        array precision_km "uncertainty radius in km (can be multiple if heterogeneous)"
        string source_crs "EPSG:4326 or historical/custom CRS identifier"
    }
%% Authority collection (single table inheritance)
    AUTHORITY {
        string _key PK
        string _id "authorities/xyz"
        string authority_type "dataset, source, relation_type, period, classification"
        text description "general description applicable to all types"
        timestamp created
        timestamp modified
        %% Dataset fields
        string title "for datasets: dataset name"
        string version "for datasets: version identifier"
        string publisher "for datasets: publishing institution"
        string license "for datasets: CC-BY, CC0, etc"
        string doi "for datasets: persistent identifier doi:10.83427/whg-dataset-123"
        %% Source fields
        string citation "for sources: bibliographic citation"
        array source_type "for sources: manuscript, inscription, archaeological, published, etc"
        string record_id "for sources: identifier in original source/dataset"
        %% Relation type fields
        string label "for relation_types, periods, classifications: machine-readable identifier"
        string inverse "for relation_types: inverse relation label"
        array domain "for relation_types: valid subject entity types"
        array range "for relation_types: valid object entity types"
        %% Period fields (from PeriodO)
        bigint start_earliest "for periods: temporal bounds"
        bigint start_latest "for periods: temporal bounds"
        bigint stop_earliest "for periods: temporal bounds"
        bigint stop_latest "for periods: temporal bounds"
        %% Classification fields
        string classification_system "for classifications: geonames_fclasses, aat_getty, custom"
        string classification_code "for classifications: A.ADM1, P.PPLA, H.STM, S.ARCH, etc"
        string classification_label "for classifications: human-readable name"
        %% Common fields
        string uri "for all types: external URI (PeriodO, source URL, dataset landing page, authority gazetteer)"
    }

Fig. 1.10 Entity–relationship diagram for the WHG v4 data model.¶

Note

The model, its formal expression, and its storage. This section describes the WHG v4 data model as a graph: SpatialEntities, Attestations, and the Names, Geometries, Timespans, Types and Authorities that attestations bundle together. The model is formalised as PLATO, the Place Attestation Ontology, which also defines its JSON and RDF serialisations. The Linked Places Format (LPF) is PLATO’s single-object-attestation profile, and remains a supported input and output format.

A graph model does not require a graph database. In WHG the attestation model is held in PostgreSQL/PostGIS, with Elasticsearch serving search. That choice was tested against ArangoDB and an RDF triplestore on real and production-scale data, as set out in the database assessment addendum.

Where these pages speak of “collections”, “edges” or “nodes”, read them as describing the logical structure, not a storage layout. AUTHORITY reference data (datasets, sources, relation types, periods, certainty levels) is still unified behind one authority_type discriminator, and Attestations remain first-class: each has its own identifier, carries certainty, notes and provenance, and links a SpatialEntity to what it attests.