Skip to content

ontocast.check

Model-free checks of a user-supplied facts graph.

Modules:

Name Description
facts

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

messages

Messages of the facts check, one per kind, written for a person.

report

Report models for the facts check.

scope

Which subjects of a facts graph are instances.

Attributes

__all__ = ['FactsCheckFinding', 'FactsCheckKind', 'FactsCheckMetrics', 'FactsCheckReport', 'catalog_schema_terms', 'check_facts', 'declared_terms', 'instances'] module-attribute

Classes

FactsCheckFinding

Bases: BaseModel

One problem found in a facts graph.

Source code in ontocast/check/report.py
class FactsCheckFinding(BaseModel):
    """One problem found in a facts graph."""

    kind: FactsCheckKind
    severity: Literal["error", "warning"]
    message: str
    subject: str | None = None
    predicate: str | None = None
    value: str | None = None
    suggestions: list[str] = Field(default_factory=list)
    source_shape: str | None = None

Attributes

kind instance-attribute
message instance-attribute
predicate = None class-attribute instance-attribute
severity instance-attribute
source_shape = None class-attribute instance-attribute
subject = None class-attribute instance-attribute
suggestions = Field(default_factory=list) class-attribute instance-attribute
value = None class-attribute instance-attribute

FactsCheckKind

Bases: StrEnum

Kind of a finding; the value is the snake_case member name.

Source code in ontocast/check/report.py
class FactsCheckKind(StrEnum):
    """Kind of a finding; the value is the snake_case member name."""

    NON_CATALOG_VOCABULARY = "non_catalog_vocabulary"
    UNKNOWN_TERM = "unknown_term"
    DOMAIN_VIOLATION = "domain_violation"
    UNTYPED_VALUE = "untyped_value"
    INVALID_LITERAL = "invalid_literal"
    TEMPORAL_RANGE_MISMATCH = "temporal_range_mismatch"
    FUNCTIONAL_VIOLATION = "functional_violation"
    SHACL = "shacl"
    UNTYPED_INSTANCE = "untyped_instance"
    ISOLATED_INSTANCE = "isolated_instance"
    SILENT_INSTANCE = "silent_instance"
    DANGLING_REFERENCE = "dangling_reference"
    TWIN_LABELS = "twin_labels"
    CATALOG_SUBJECT = "catalog_subject"
    SCHEMA_IN_FACTS = "schema_in_facts"

Attributes

CATALOG_SUBJECT = 'catalog_subject' class-attribute instance-attribute
DANGLING_REFERENCE = 'dangling_reference' class-attribute instance-attribute
DOMAIN_VIOLATION = 'domain_violation' class-attribute instance-attribute
FUNCTIONAL_VIOLATION = 'functional_violation' class-attribute instance-attribute
INVALID_LITERAL = 'invalid_literal' class-attribute instance-attribute
ISOLATED_INSTANCE = 'isolated_instance' class-attribute instance-attribute
NON_CATALOG_VOCABULARY = 'non_catalog_vocabulary' class-attribute instance-attribute
SCHEMA_IN_FACTS = 'schema_in_facts' class-attribute instance-attribute
SHACL = 'shacl' class-attribute instance-attribute
SILENT_INSTANCE = 'silent_instance' class-attribute instance-attribute
TEMPORAL_RANGE_MISMATCH = 'temporal_range_mismatch' class-attribute instance-attribute
TWIN_LABELS = 'twin_labels' class-attribute instance-attribute
UNKNOWN_TERM = 'unknown_term' class-attribute instance-attribute
UNTYPED_INSTANCE = 'untyped_instance' class-attribute instance-attribute
UNTYPED_VALUE = 'untyped_value' class-attribute instance-attribute

FactsCheckMetrics

Bases: BaseModel

Size and shape figures of the checked graph.

Source code in ontocast/check/report.py
class FactsCheckMetrics(BaseModel):
    """Size and shape figures of the checked graph."""

    triples: int
    instances: int
    isolated: int
    untyped: int
    twin_labels: int

Attributes

instances instance-attribute
isolated instance-attribute
triples instance-attribute
twin_labels instance-attribute
untyped instance-attribute

FactsCheckReport

Bases: BaseModel

Outcome of a facts check.

counts maps kind value to severity to number of findings and is complete even when findings is truncated; findings_total is the untruncated count.

Source code in ontocast/check/report.py
class FactsCheckReport(BaseModel):
    """Outcome of a facts check.

    `counts` maps kind value to severity to number of findings and is complete
    even when `findings` is truncated; `findings_total` is the untruncated count.
    """

    findings: list[FactsCheckFinding]
    findings_total: int
    counts: dict[str, dict[str, int]]
    metrics: FactsCheckMetrics
    shacl_evaluated: bool | None
    catalog_empty: bool

Attributes

catalog_empty instance-attribute
counts instance-attribute
findings instance-attribute
findings_total instance-attribute
metrics instance-attribute
shacl_evaluated instance-attribute

Functions:

catalog_schema_terms(catalog)

Return the IRIs the catalog declares as a class or property.

Evidence is explicit typing, a domain or range, rdfs:subClassOf, rdfs:subPropertyOf and rdf:type-object position. The catalog's individuals (ex:Paris a ex:City, SKOS concepts, units) are not terms: statements about them are facts.

Source code in ontocast/check/scope.py
def catalog_schema_terms(catalog: RDFGraph | None) -> set[str]:
    """Return the IRIs the catalog declares as a class or property.

    Evidence is explicit typing, a domain or range, ``rdfs:subClassOf``,
    ``rdfs:subPropertyOf`` and ``rdf:type``-object position. The catalog's
    individuals (``ex:Paris a ex:City``, SKOS concepts, units) are not terms:
    statements about them are facts.
    """
    if catalog is None:
        return set()
    properties, classes = catalog_term_evidence(catalog)
    terms = properties | classes | declared_terms(catalog)
    for subject, obj in catalog.subject_objects(RDFS.subPropertyOf):
        terms.update(str(term) for term in (subject, obj) if isinstance(term, URIRef))
    return terms

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,
    )

declared_terms(graph)

Return IRIs the graph itself declares as a class or property.

Source code in ontocast/check/scope.py
def declared_terms(graph: Graph) -> set[str]:
    """Return IRIs the graph itself declares as a class or property."""
    return {
        str(subject)
        for declaring in _DECLARING_TYPES
        for subject in graph.subjects(RDF.type, declaring)
        if isinstance(subject, URIRef)
    }

instances(graph, *, catalog_terms, standard_namespaces, restrict_to=None)

Return the IRI subjects of graph that are instances.

An instance is not a catalog term (a class or property, :func:catalog_schema_terms), not declared in the graph, and not under a standard or well-known namespace. Blank-node and literal subjects are ignored. With restrict_to, only IRIs under those namespaces are kept.

Source code in ontocast/check/scope.py
def instances(
    graph: Graph,
    *,
    catalog_terms: AbstractSet[str],
    standard_namespaces: tuple[str, ...],
    restrict_to: Sequence[str] | None = None,
) -> set[URIRef]:
    """Return the IRI subjects of `graph` that are instances.

    An instance is not a catalog term (a class or property,
    :func:`catalog_schema_terms`), not declared in the graph, and not under
    a standard or well-known namespace. Blank-node and literal subjects are
    ignored. With `restrict_to`, only IRIs under those namespaces are kept.
    """
    declared = declared_terms(graph)
    result: set[URIRef] = set()
    for subject in set(graph.subjects()):
        if not isinstance(subject, URIRef):
            continue
        iri = str(subject)
        if iri in catalog_terms or iri in declared:
            continue
        if iri.startswith(standard_namespaces):
            continue
        if restrict_to is not None and not iri.startswith(tuple(restrict_to)):
            continue
        result.add(subject)
    return result