Skip to content

ontocast.check.facts

Check a user-supplied facts graph against a catalog, without a model.

Attributes

Vocabulary = TypingLiteral['strict', 'open'] module-attribute

Classes

Functions:

check_facts(graph, ontology_graph, shapes_graph=None, *, vocabulary='strict', additional_standard_namespaces=(), instance_namespaces=None, max_findings=None, shacl_max_triples=0)

Check a facts graph against a catalog ontology and report what is wrong.

The graph is never modified: every check that rewrites runs on a copy. With an empty or missing catalog, the checks that need one are skipped and the report says so (catalog_empty); the well-known-term checks and literal syntax still run.

Parameters:

Name Type Description Default
graph Graph

Facts graph, in the user's own namespaces.

required
ontology_graph Graph | None

Merged catalog ontology; None or empty when there is none.

required
shapes_graph Graph | None

Merged SHACL shapes, or None.

None
vocabulary Vocabulary

strict makes a term outside the catalog an error, open a warning.

'strict'
additional_standard_namespaces Sequence[str]

Namespaces treated like the standard vocabularies.

()
instance_namespaces Sequence[str] | None

When given, only subjects under these namespaces are instances.

None
max_findings int | None

Cap on the returned findings; counts and findings_total stay complete.

None
shacl_max_triples int

Skip SHACL validation above this many triples; 0 means no limit.

0

Returns:

Type Description
FactsCheckReport

The report.

Source code in ontocast/check/facts.py
def check_facts(
    graph: Graph,
    ontology_graph: Graph | None,
    shapes_graph: Graph | None = None,
    *,
    vocabulary: Vocabulary = "strict",
    additional_standard_namespaces: Sequence[str] = (),
    instance_namespaces: Sequence[str] | None = None,
    max_findings: int | None = None,
    shacl_max_triples: int = 0,
) -> FactsCheckReport:
    """Check a facts graph against a catalog ontology and report what is wrong.

    The graph is never modified: every check that rewrites runs on a copy.
    With an empty or missing catalog, the checks that need one are skipped
    and the report says so (``catalog_empty``); the well-known-term checks
    and literal syntax still run.

    Args:
        graph: Facts graph, in the user's own namespaces.
        ontology_graph: Merged catalog ontology; ``None`` or empty when there
            is none.
        shapes_graph: Merged SHACL shapes, or ``None``.
        vocabulary: ``strict`` makes a term outside the catalog an error,
            ``open`` a warning.
        additional_standard_namespaces: Namespaces treated like the standard
            vocabularies.
        instance_namespaces: When given, only subjects under these namespaces
            are instances.
        max_findings: Cap on the returned findings; ``counts`` and
            ``findings_total`` stay complete.
        shacl_max_triples: Skip SHACL validation above this many triples;
            0 means no limit.

    Returns:
        The report.
    """
    work = _rdf_copy(graph)
    catalog = _as_rdf_graph(ontology_graph)
    catalog_empty = catalog is None
    policy = ValidationPolicy(
        additional_standard_namespaces=tuple(additional_standard_namespaces),
        vocabulary=vocabulary,
    )
    # Any IRI of the catalog is acceptable vocabulary; only its classes and
    # properties are schema terms, so its individuals stay instances.
    catalog_terms = collect_catalog_terms(catalog)
    schema_terms = catalog_schema_terms(catalog)
    found = instances(
        work,
        catalog_terms=schema_terms,
        standard_namespaces=policy.standard_namespaces(),
        restrict_to=instance_namespaces,
    )
    instance_iris = {str(instance) for instance in found}
    names = _Names(work, catalog)

    findings: list[FactsCheckFinding] = []
    term_findings, complete = _term_findings(
        work, catalog, catalog_terms, policy, names
    )
    findings.extend(term_findings)
    findings.extend(_subject_findings(work, schema_terms, names))
    findings.extend(_literal_findings(work, catalog, names))
    if catalog is not None:
        findings.extend(_domain_findings(work, catalog, instance_iris, names))
        findings.extend(
            _functional_findings(
                work, catalog, catalog_terms, instance_iris, policy, names
            )
        )

    structure = _structure_findings(
        work, catalog, catalog_terms, instance_iris, policy, names
    )
    findings.extend(structure.findings)
    shacl_evaluated: bool | None = None
    shapes = _as_rdf_graph(shapes_graph)
    if shapes is not None:
        shacl_findings = _shacl_findings(
            work, catalog, shapes, shacl_max_triples, names
        )
        if shacl_findings is not None:
            findings.extend(shacl_findings)
            shacl_evaluated = True
    findings.sort(key=_sort_key)

    counts: dict[str, dict[str, int]] = {}
    for finding in findings:
        by_severity = counts.setdefault(finding.kind.value, {})
        by_severity[finding.severity] = by_severity.get(finding.severity, 0) + 1
    total = len(findings)
    if max_findings is not None:
        findings = findings[:max_findings]
    # Suggestions cost a ranking against the catalog each: only the findings
    # returned get them.
    findings = [
        complete[id(finding)]() if id(finding) in complete else finding
        for finding in findings
    ]
    return FactsCheckReport(
        findings=findings,
        findings_total=total,
        counts=counts,
        metrics=FactsCheckMetrics(
            triples=len(graph),
            instances=len(found),
            isolated=structure.isolated,
            untyped=structure.untyped,
            twin_labels=structure.twin_labels,
        ),
        shacl_evaluated=shacl_evaluated,
        catalog_empty=catalog_empty,
    )