Skip to content

ontocast.link.links

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

A pure function of the document graph and the catalog's declarations. It reads nothing else, so a document's links never depend on which documents were linked before it, and the resolution graph built one document at a time equals the one built from all of them at once.

MATCH = ONTOCAST.Match module-attribute

MATCHED_TEXT = ONTOCAST.matchedText module-attribute

MATCH_CLASS = ONTOCAST.matchClass module-attribute

MATCH_KIND = ONTOCAST.matchKind module-attribute

MATCH_PROPERTY = ONTOCAST.matchProperty module-attribute

MATCH_VALUE = ONTOCAST.matchValue module-attribute

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)

key_value(term, catalog_terms)

The normalised form of term as a key value, or None when it cannot be one.

A literal counts: strings trimmed and case-folded, typed values in the normal form triple stores converge on. An IRI counts only when the catalog holds it, because a document-local IRI means nothing in another document.

Source code in ontocast/link/links.py
def key_value(term: Node, catalog_terms: frozenset[str]) -> str | None:
    """The normalised form of ``term`` as a key value, or None when it cannot be one.

    A literal counts: strings trimmed and case-folded, typed values in the
    normal form triple stores converge on. An IRI counts only when the catalog
    holds it, because a document-local IRI means nothing in another document.
    """
    if isinstance(term, URIRef):
        return str(term) if str(term) in catalog_terms else None
    if not isinstance(term, Literal):
        return None
    literal = canonical_literal(term)
    assert isinstance(literal, Literal)
    lexical = str(literal).strip()
    if not lexical:
        return None
    if literal.datatype in _STRING_DATATYPES:
        return lexical.casefold()
    return f"{lexical}^^{literal.datatype}"

linkable_instances(graph, declarations, value_classes)

The entities of a document graph that can carry links.

A typed IRI subject that is not a catalog term, not a value (R1: values are reached through their entity, never resolved), and not the document node.

Source code in ontocast/link/links.py
def linkable_instances(
    graph: RDFGraph,
    declarations: IdentityDeclarations,
    value_classes: frozenset[str],
) -> list[URIRef]:
    """The entities of a document graph that can carry links.

    A typed IRI subject that is not a catalog term, not a value (R1: values are
    reached through their entity, never resolved), and not the document node.
    """
    found: set[URIRef] = set()
    for subject in graph.subjects(RDF.type, None):
        if not isinstance(subject, URIRef) or subject in found:
            continue
        if str(subject) in declarations.catalog_terms:
            continue
        types = _types(graph, subject)
        if not types or FOAF.Document in map(URIRef, types):
            continue
        if any(t in value_classes for t in types):
            continue
        found.add(subject)
    return sorted(found, key=str)

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}")