Skip to content

ontocast.link

Cross-document identity: link each document's entities, resolve them on read.

Document graphs are never changed. For each document, :func:links_for derives a links graph (<graph>/identity-links) from the document and the catalog's declarations alone: one skos:closeMatch link from an entity to a match node per declared key value, inverse-functional value, caller identifier, or normalised name of a globally named class. The resolution graph is the union of these links graphs; :func:build, :func:add_documents and :func:remove_documents keep it in step with the documents. :func:cluster_of reads which entities are one, with vetoes.

Modules:

Name Description
clusters

Read-time clusters: which stored entities are one, from the resolution graph.

declarations

What the catalog declares about identity across documents.

links

The link pass: one document's facts graph to its identity links graph.

resolution

The resolution graph: every document's identity links, one named graph each.

__all__ = ['ClusterMember', 'EntityCluster', 'IdentityDeclarations', 'KeptApart', 'ResolutionReport', 'add_documents', 'build', 'cluster_of', 'document_graphs', 'identity_links_graph_uri', 'links_for', 'match_node_iri', 'remove_documents', 'write_document_links'] module-attribute

ClusterMember

Bases: BaseModel

One entity of a cluster.

Source code in ontocast/link/clusters.py
class ClusterMember(BaseModel):
    """One entity of a cluster."""

    iri: str
    graph: str = Field(description="The document graph that holds the entity.")
    labels: list[str] = Field(default_factory=list)
    types: list[str] = Field(default_factory=list)
    reason: str = Field(
        description="`self` for the entity asked about, else the strongest kind "
        "of link it shares with the cluster (key, ifp, identifier, label)."
    )
    via: list[str] = Field(
        default_factory=list, description="Match nodes it shares with the cluster."
    )

Attributes

graph = Field(description='The document graph that holds the entity.') class-attribute instance-attribute
iri instance-attribute
labels = Field(default_factory=list) class-attribute instance-attribute
reason = Field(description='`self` for the entity asked about, else the strongest kind of link it shares with the cluster (key, ifp, identifier, label).') class-attribute instance-attribute
types = Field(default_factory=list) class-attribute instance-attribute
via = Field(default_factory=list, description='Match nodes it shares with the cluster.') class-attribute instance-attribute

EntityCluster

Bases: BaseModel

The entities stored as one with iri, and the candidates kept apart.

Source code in ontocast/link/clusters.py
class EntityCluster(BaseModel):
    """The entities stored as one with ``iri``, and the candidates kept apart."""

    iri: str
    members: list[ClusterMember]
    kept_apart: list[KeptApart] = Field(default_factory=list)
    truncated: bool = Field(
        default=False,
        description="The candidate set reached its cap; some candidates were not read.",
    )

Attributes

iri instance-attribute
kept_apart = Field(default_factory=list) class-attribute instance-attribute
members instance-attribute
truncated = Field(default=False, description='The candidate set reached its cap; some candidates were not read.') class-attribute instance-attribute

IdentityDeclarations

Bases: BaseModel

The catalog's identity declarations, read once per catalog state.

Attributes:

Name Type Description
globally_named dict[str, bool]

Each class with ontocast:globallyNamed stated, and the stated value. When catalog heads disagree, false wins.

parents dict[str, frozenset[str]]

Each class's rdfs:subClassOf parents.

keys dict[str, tuple[tuple[str, ...], ...]]

Each class's owl:hasKey property lists.

inverse_functional frozenset[str]

Properties declared owl:InverseFunctionalProperty.

functional frozenset[str]

Properties the catalog caps at one value (owl:FunctionalProperty or a max-cardinality-1 restriction).

disjoint frozenset[frozenset[str]]

Class pairs declared disjoint.

catalog_terms frozenset[str]

Every IRI the catalog declares or references.

Source code in ontocast/link/declarations.py
class IdentityDeclarations(BaseModel):
    """The catalog's identity declarations, read once per catalog state.

    Attributes:
        globally_named: Each class with ``ontocast:globallyNamed`` stated, and
            the stated value. When catalog heads disagree, ``false`` wins.
        parents: Each class's ``rdfs:subClassOf`` parents.
        keys: Each class's ``owl:hasKey`` property lists.
        inverse_functional: Properties declared ``owl:InverseFunctionalProperty``.
        functional: Properties the catalog caps at one value
            (``owl:FunctionalProperty`` or a max-cardinality-1 restriction).
        disjoint: Class pairs declared disjoint.
        catalog_terms: Every IRI the catalog declares or references.
    """

    model_config = ConfigDict(frozen=True)

    globally_named: dict[str, bool] = Field(default_factory=dict)
    parents: dict[str, frozenset[str]] = Field(default_factory=dict)
    keys: dict[str, tuple[tuple[str, ...], ...]] = Field(default_factory=dict)
    inverse_functional: frozenset[str] = frozenset()
    functional: frozenset[str] = frozenset()
    disjoint: frozenset[frozenset[str]] = frozenset()
    catalog_terms: frozenset[str] = frozenset()

    @classmethod
    def of(cls, graphs: Iterable[RDFGraph]) -> IdentityDeclarations:
        """The declarations stated across ``graphs``."""
        globally_named: dict[str, bool] = {}
        parents: dict[str, set[str]] = {}
        keys: dict[str, set[tuple[str, ...]]] = {}
        inverse_functional: set[str] = set()
        functional: set[str] = set()
        disjoint: set[frozenset[str]] = set()
        catalog_terms: set[str] = set()
        for graph in graphs:
            for cls_iri, value in graph.subject_objects(GLOBALLY_NAMED):
                if not isinstance(cls_iri, URIRef) or not isinstance(value, Literal):
                    continue
                stated = _as_bool(value)
                if stated is None:
                    continue
                key = str(cls_iri)
                globally_named[key] = globally_named.get(key, True) and stated
            for child, parent in graph.subject_objects(RDFS.subClassOf):
                if isinstance(child, URIRef) and isinstance(parent, URIRef):
                    parents.setdefault(str(child), set()).add(str(parent))
            for cls_iri, members in graph.subject_objects(OWL.hasKey):
                if not isinstance(cls_iri, URIRef) or not isinstance(members, BNode):
                    continue
                props = tuple(
                    sorted(
                        str(m)
                        for m in Collection(graph, members)
                        if isinstance(m, URIRef)
                    )
                )
                if props:
                    keys.setdefault(str(cls_iri), set()).add(props)
            for prop in graph.subjects(RDF.type, OWL.InverseFunctionalProperty):
                if isinstance(prop, URIRef):
                    inverse_functional.add(str(prop))
            functional |= {str(p) for p in harvest_max_one_predicates(graph)}
            disjoint |= {
                frozenset(str(c) for c in pair)
                for pair in harvest_disjoint_classes(graph)
            }
            catalog_terms |= collect_catalog_terms(graph)
        return cls(
            globally_named=globally_named,
            parents={k: frozenset(v) for k, v in parents.items()},
            keys={k: tuple(sorted(v)) for k, v in keys.items()},
            inverse_functional=frozenset(inverse_functional),
            functional=frozenset(functional),
            disjoint=frozenset(disjoint),
            catalog_terms=frozenset(catalog_terms),
        )

    @property
    def declares_anything(self) -> bool:
        """Whether any class or property can produce a link."""
        return (
            any(self.globally_named.values())
            or bool(self.keys)
            or bool(self.inverse_functional)
        )

    def ancestors(self, class_iri: str) -> frozenset[str]:
        """``class_iri`` and every class above it."""
        seen: set[str] = set()
        frontier = [class_iri]
        while frontier:
            current = frontier.pop()
            if current in seen:
                continue
            seen.add(current)
            frontier.extend(self.parents.get(current, ()))
        return frozenset(seen)

    def declaring_classes(self, types: Iterable[str]) -> frozenset[str]:
        """The globally named classes an instance of ``types`` belongs to.

        Walks up from each type and stops at the first class on each path that
        states the annotation: ``true`` makes it a declaring class, ``false``
        stops the path.
        """
        found: set[str] = set()
        seen: set[str] = set()
        frontier = list(types)
        while frontier:
            current = frontier.pop()
            if current in seen:
                continue
            seen.add(current)
            stated = self.globally_named.get(current)
            if stated is not None:
                if stated:
                    found.add(current)
                continue
            frontier.extend(self.parents.get(current, ()))
        return frozenset(found)

    def keys_for(self, types: Iterable[str]) -> list[tuple[str, tuple[str, ...]]]:
        """Each ``(class, properties)`` key that applies to an instance of ``types``."""
        classes: set[str] = set()
        for type_iri in types:
            classes |= self.ancestors(type_iri)
        return sorted(
            (cls_iri, props)
            for cls_iri in classes
            for props in self.keys.get(cls_iri, ())
        )

    def are_disjoint(
        self, left_types: Iterable[str], right_types: Iterable[str]
    ) -> bool:
        """Whether some class of one typing is declared disjoint with one of the other."""
        if not self.disjoint:
            return False
        left = set().union(*(self.ancestors(t) for t in left_types))
        right = set().union(*(self.ancestors(t) for t in right_types))
        return any(frozenset((a, b)) in self.disjoint for a in left for b in right)

Attributes

catalog_terms = frozenset() class-attribute instance-attribute
declares_anything property

Whether any class or property can produce a link.

disjoint = frozenset() class-attribute instance-attribute
functional = frozenset() class-attribute instance-attribute
globally_named = Field(default_factory=dict) class-attribute instance-attribute
inverse_functional = frozenset() class-attribute instance-attribute
keys = Field(default_factory=dict) class-attribute instance-attribute
model_config = ConfigDict(frozen=True) class-attribute instance-attribute
parents = Field(default_factory=dict) class-attribute instance-attribute

Methods:

ancestors(class_iri)

class_iri and every class above it.

Source code in ontocast/link/declarations.py
def ancestors(self, class_iri: str) -> frozenset[str]:
    """``class_iri`` and every class above it."""
    seen: set[str] = set()
    frontier = [class_iri]
    while frontier:
        current = frontier.pop()
        if current in seen:
            continue
        seen.add(current)
        frontier.extend(self.parents.get(current, ()))
    return frozenset(seen)
are_disjoint(left_types, right_types)

Whether some class of one typing is declared disjoint with one of the other.

Source code in ontocast/link/declarations.py
def are_disjoint(
    self, left_types: Iterable[str], right_types: Iterable[str]
) -> bool:
    """Whether some class of one typing is declared disjoint with one of the other."""
    if not self.disjoint:
        return False
    left = set().union(*(self.ancestors(t) for t in left_types))
    right = set().union(*(self.ancestors(t) for t in right_types))
    return any(frozenset((a, b)) in self.disjoint for a in left for b in right)
declaring_classes(types)

The globally named classes an instance of types belongs to.

Walks up from each type and stops at the first class on each path that states the annotation: true makes it a declaring class, false stops the path.

Source code in ontocast/link/declarations.py
def declaring_classes(self, types: Iterable[str]) -> frozenset[str]:
    """The globally named classes an instance of ``types`` belongs to.

    Walks up from each type and stops at the first class on each path that
    states the annotation: ``true`` makes it a declaring class, ``false``
    stops the path.
    """
    found: set[str] = set()
    seen: set[str] = set()
    frontier = list(types)
    while frontier:
        current = frontier.pop()
        if current in seen:
            continue
        seen.add(current)
        stated = self.globally_named.get(current)
        if stated is not None:
            if stated:
                found.add(current)
            continue
        frontier.extend(self.parents.get(current, ()))
    return frozenset(found)
keys_for(types)

Each (class, properties) key that applies to an instance of types.

Source code in ontocast/link/declarations.py
def keys_for(self, types: Iterable[str]) -> list[tuple[str, tuple[str, ...]]]:
    """Each ``(class, properties)`` key that applies to an instance of ``types``."""
    classes: set[str] = set()
    for type_iri in types:
        classes |= self.ancestors(type_iri)
    return sorted(
        (cls_iri, props)
        for cls_iri in classes
        for props in self.keys.get(cls_iri, ())
    )
of(graphs) classmethod

The declarations stated across graphs.

Source code in ontocast/link/declarations.py
@classmethod
def of(cls, graphs: Iterable[RDFGraph]) -> IdentityDeclarations:
    """The declarations stated across ``graphs``."""
    globally_named: dict[str, bool] = {}
    parents: dict[str, set[str]] = {}
    keys: dict[str, set[tuple[str, ...]]] = {}
    inverse_functional: set[str] = set()
    functional: set[str] = set()
    disjoint: set[frozenset[str]] = set()
    catalog_terms: set[str] = set()
    for graph in graphs:
        for cls_iri, value in graph.subject_objects(GLOBALLY_NAMED):
            if not isinstance(cls_iri, URIRef) or not isinstance(value, Literal):
                continue
            stated = _as_bool(value)
            if stated is None:
                continue
            key = str(cls_iri)
            globally_named[key] = globally_named.get(key, True) and stated
        for child, parent in graph.subject_objects(RDFS.subClassOf):
            if isinstance(child, URIRef) and isinstance(parent, URIRef):
                parents.setdefault(str(child), set()).add(str(parent))
        for cls_iri, members in graph.subject_objects(OWL.hasKey):
            if not isinstance(cls_iri, URIRef) or not isinstance(members, BNode):
                continue
            props = tuple(
                sorted(
                    str(m)
                    for m in Collection(graph, members)
                    if isinstance(m, URIRef)
                )
            )
            if props:
                keys.setdefault(str(cls_iri), set()).add(props)
        for prop in graph.subjects(RDF.type, OWL.InverseFunctionalProperty):
            if isinstance(prop, URIRef):
                inverse_functional.add(str(prop))
        functional |= {str(p) for p in harvest_max_one_predicates(graph)}
        disjoint |= {
            frozenset(str(c) for c in pair)
            for pair in harvest_disjoint_classes(graph)
        }
        catalog_terms |= collect_catalog_terms(graph)
    return cls(
        globally_named=globally_named,
        parents={k: frozenset(v) for k, v in parents.items()},
        keys={k: tuple(sorted(v)) for k, v in keys.items()},
        inverse_functional=frozenset(inverse_functional),
        functional=frozenset(functional),
        disjoint=frozenset(disjoint),
        catalog_terms=frozenset(catalog_terms),
    )

KeptApart

Bases: BaseModel

A candidate that shares a match node with the cluster but is not in it.

Source code in ontocast/link/clusters.py
class KeptApart(BaseModel):
    """A candidate that shares a match node with the cluster but is not in it."""

    iri: str
    graph: str
    veto: str = Field(description="Why it is not one entity with the cluster.")

Attributes

graph instance-attribute
iri instance-attribute
veto = Field(description='Why it is not one entity with the cluster.') class-attribute instance-attribute

ResolutionReport

Bases: BaseModel

What one operation on the resolution graph did.

Source code in ontocast/link/resolution.py
class ResolutionReport(BaseModel):
    """What one operation on the resolution graph did."""

    documents: int = Field(default=0, description="Documents whose links were written.")
    links: int = Field(default=0, description="Links written.")
    removed: int = Field(default=0, description="Links graphs dropped.")

Attributes

documents = Field(default=0, description='Documents whose links were written.') class-attribute instance-attribute
removed = Field(default=0, description='Links graphs dropped.') class-attribute instance-attribute

add_documents(store, graph_uris, declarations, *, domain, value_classes=frozenset()) async

Write the links graph of each document graph in graph_uris.

A document graph that is not stored has its links graph dropped.

Source code in ontocast/link/resolution.py
async def add_documents(
    store: TripleStoreManager,
    graph_uris: Iterable[str],
    declarations: IdentityDeclarations,
    *,
    domain: str,
    value_classes: frozenset[str] = frozenset(),
) -> ResolutionReport:
    """Write the links graph of each document graph in ``graph_uris``.

    A document graph that is not stored has its links graph dropped.
    """
    report = ResolutionReport()
    for graph_uri in sorted(set(graph_uris)):
        graph = await store.afetch_named_graph(graph_uri, store="facts")
        if graph is None:
            await store.drop_named_graph(
                identity_links_graph_uri(graph_uri), store="facts"
            )
            report.removed += 1
            continue
        links = links_for(
            graph, declarations, domain=domain, value_classes=value_classes
        )
        await write_document_links(store, graph_uri, links)
        report.documents += 1
        report.links += count_links(links)
    return report

build(store, declarations, *, domain, value_classes=frozenset()) async

Recompute the whole resolution graph from the stored document graphs.

Links graphs whose document graph is gone are dropped. Running it twice gives the same store.

Source code in ontocast/link/resolution.py
async def build(
    store: TripleStoreManager,
    declarations: IdentityDeclarations,
    *,
    domain: str,
    value_classes: frozenset[str] = frozenset(),
) -> ResolutionReport:
    """Recompute the whole resolution graph from the stored document graphs.

    Links graphs whose document graph is gone are dropped. Running it twice
    gives the same store.
    """
    documents = await document_graphs(store)
    expected = {identity_links_graph_uri(g) for g in documents}
    stale = [g for g in await links_graphs(store) if g not in expected]
    for graph_uri in stale:
        await store.drop_named_graph(graph_uri, store="facts")
    report = await add_documents(
        store, documents, declarations, domain=domain, value_classes=value_classes
    )
    report.removed += len(stale)
    logger.info(
        "Resolution graph built: %d document(s), %d link(s), %d stale graph(s) dropped",
        report.documents,
        report.links,
        len(stale),
    )
    return report

cluster_of(store, declarations, iri, *, max_candidates=DEFAULT_MAX_CANDIDATES) async

The cluster of the stored entity iri, or None when no document holds it.

Parameters:

Name Type Description Default
store TripleStoreManager

The triple store holding the documents and their links graphs.

required
declarations IdentityDeclarations

The catalog's identity declarations.

required
iri str

An entity of some document graph.

required
max_candidates int

Stop collecting candidates beyond this many.

DEFAULT_MAX_CANDIDATES
Source code in ontocast/link/clusters.py
async def cluster_of(
    store: TripleStoreManager,
    declarations: IdentityDeclarations,
    iri: str,
    *,
    max_candidates: int = DEFAULT_MAX_CANDIDATES,
) -> EntityCluster | None:
    """The cluster of the stored entity ``iri``, or None when no document holds it.

    Args:
        store: The triple store holding the documents and their links graphs.
        declarations: The catalog's identity declarations.
        iri: An entity of some document graph.
        max_candidates: Stop collecting candidates beyond this many.
    """
    nodes, edges, truncated = await _candidates(store, iri, max_candidates)
    candidates = sorted({iri} | {e for _, members in nodes.items() for e in members})
    entities = await _read_entities(store, candidates)
    if iri not in entities:
        return None
    ordered_edges = _ordered_edges(nodes, edges, entities)
    parent = {e: e for e in entities}
    members_of = {e: [e] for e in entities}

    def find(x: str) -> str:
        while parent[x] != x:
            parent[x] = parent[parent[x]]
            x = parent[x]
        return x

    for _, _, left, right in ordered_edges:
        root_left, root_right = find(left), find(right)
        if root_left == root_right:
            continue
        if any(
            _veto(entities[a], entities[b], declarations)
            for a in members_of[root_left]
            for b in members_of[root_right]
        ):
            continue
        keep, drop = sorted((root_left, root_right))
        parent[drop] = keep
        members_of[keep].extend(members_of.pop(drop))

    root = find(iri)
    cluster = sorted(members_of[root])
    in_cluster = set(cluster)
    shared = _shared_nodes(nodes, edges, in_cluster)
    members = [
        ClusterMember(
            iri=e,
            graph=entities[e].graph,
            labels=sorted(entities[e].labels),
            types=sorted(entities[e].types),
            reason="self" if e == iri else _strongest(shared.get(e, [])),
            via=sorted(node for node, _ in shared.get(e, [])),
        )
        for e in cluster
    ]
    kept_apart = [
        KeptApart(
            iri=e,
            graph=entities[e].graph,
            veto=next(
                (
                    reason
                    for other in cluster
                    if (reason := _veto(entities[e], entities[other], declarations))
                ),
                "joined another cluster",
            ),
        )
        for e in sorted(entities)
        if e not in in_cluster
    ]
    return EntityCluster(
        iri=iri, members=members, kept_apart=kept_apart, truncated=truncated
    )

document_graphs(store) async

Every document graph in the facts partition, auxiliary graphs excluded.

Source code in ontocast/link/resolution.py
async def document_graphs(store: TripleStoreManager) -> list[str]:
    """Every document graph in the facts partition, auxiliary graphs excluded."""
    rows = await store.aselect(_NAMED_GRAPHS_QUERY, store="facts")
    return sorted(
        {g for row in rows if (g := row.get("g")) and not is_auxiliary_graph(g)}
    )

The identity links graph of the facts graph graph_uri.

Source code in ontocast/link/links.py
def identity_links_graph_uri(graph_uri: str) -> str:
    """The identity links graph of the facts graph ``graph_uri``."""
    return auxiliary_graph_uri(graph_uri, IDENTITY_LINKS_SUFFIX)

The identity links of one document's facts graph.

Each entity gets one skos:closeMatch link per:

  • owl:hasKey that applies to its types and whose properties all have key values (one link per combination of values);
  • value of an owl:InverseFunctionalProperty;
  • dcterms:identifier on an entity the document node links to (the caller's document metadata), scoped to each of its types;
  • normalised rdfs:label / skos:altLabel, when one of its types is under a globally named class.

Parameters:

Name Type Description Default
graph RDFGraph

One document's facts graph, as written to the store.

required
declarations IdentityDeclarations

The catalog's identity declarations.

required
domain str

The deployment domain; match nodes are minted under it.

required
value_classes frozenset[str]

Classes whose instances are values, never linked.

frozenset()

Returns:

Name Type Description
RDFGraph RDFGraph

The links graph; empty when nothing is declared or matched.

Source code in ontocast/link/links.py
def links_for(
    graph: RDFGraph,
    declarations: IdentityDeclarations,
    *,
    domain: str,
    value_classes: frozenset[str] = frozenset(),
) -> RDFGraph:
    """The identity links of one document's facts graph.

    Each entity gets one ``skos:closeMatch`` link per:

    - ``owl:hasKey`` that applies to its types and whose properties all have
      key values (one link per combination of values);
    - value of an ``owl:InverseFunctionalProperty``;
    - ``dcterms:identifier`` on an entity the document node links to (the
      caller's document metadata), scoped to each of its types;
    - normalised ``rdfs:label`` / ``skos:altLabel``, when one of its types is
      under a globally named class.

    Args:
        graph: One document's facts graph, as written to the store.
        declarations: The catalog's identity declarations.
        domain: The deployment domain; match nodes are minted under it.
        value_classes: Classes whose instances are values, never linked.

    Returns:
        RDFGraph: The links graph; empty when nothing is declared or matched.
    """
    builder = _Builder(domain)
    if not declarations.declares_anything and not _has_metadata_identifiers(graph):
        return builder.graph
    terms = declarations.catalog_terms
    metadata_entities = _metadata_entities(graph)
    for entity in linkable_instances(graph, declarations, value_classes):
        types = _types(graph, entity)
        _key_links(builder, graph, entity, types, declarations, terms)
        _ifp_links(builder, graph, entity, declarations, terms)
        if entity in metadata_entities:
            _identifier_links(builder, graph, entity, types, terms)
        _label_links(builder, graph, entity, types, declarations)
    return builder.graph

match_node_iri(domain, payload)

The match node for payload under domain: the same IRI everywhere.

Source code in ontocast/link/links.py
def match_node_iri(domain: str, payload: dict[str, object]) -> URIRef:
    """The match node for ``payload`` under ``domain``: the same IRI everywhere."""
    canonical = json.dumps(payload, sort_keys=True, separators=(",", ":"))
    digest = hashlib.sha256(canonical.encode("utf-8")).hexdigest()[:16]
    return URIRef(f"{domain.rstrip('/')}/match/{digest}")

remove_documents(store, graph_uris) async

Drop the links graphs of the document graphs in graph_uris.

Source code in ontocast/link/resolution.py
async def remove_documents(
    store: TripleStoreManager, graph_uris: Iterable[str]
) -> ResolutionReport:
    """Drop the links graphs of the document graphs in ``graph_uris``."""
    report = ResolutionReport()
    for graph_uri in sorted(set(graph_uris)):
        await store.drop_named_graph(identity_links_graph_uri(graph_uri), store="facts")
        report.removed += 1
    return report

Replace the links graph of the document graph_uri with links.

Source code in ontocast/link/resolution.py
async def write_document_links(
    store: TripleStoreManager,
    graph_uri: str,
    links: RDFGraph,
) -> None:
    """Replace the links graph of the document ``graph_uri`` with ``links``."""
    target = identity_links_graph_uri(graph_uri)
    if len(links) == 0:
        await store.drop_named_graph(target, store="facts")
        return
    await store.aserialize(links, graph_uri=target)