Checking facts¶
check_facts inspects a facts graph you already have against a catalog
ontology, without a model call and without changing the graph. It reports
what would not survive as clean facts: terms the catalog does not define,
values of the wrong kind, instances nothing says anything about.
from ontocast import check_facts
from ontocast.onto.rdfgraph import RDFGraph
facts = RDFGraph.from_file("facts.ttl")
catalog = RDFGraph.from_file("ontology.ttl")
report = check_facts(facts, catalog, vocabulary="strict")
From the command line:
ontocast check facts.ttl --ontology-dir ontologies/ --shapes-dir shapes/
ontocast check part1.ttl part2.ttl --ontology-dir ontologies/ --vocabulary open --json
ontocast check facts.ttl --tenant T --project P # catalog held by the configured store
The command needs the server extra (pip install "ontocast[server]");
SHACL shapes are evaluated only with the shacl extra installed. Several
files are merged into one graph first. The text output opens with a summary
line (triples, instances, errors, warnings). Exit status is 0 without error
findings, 1 with any, and 2 when the check cannot run: a file cannot be
parsed or holds no triples, or the catalog cannot be loaded.
--tenant/--project read the catalog and shapes from the triple store, so
they need the same store settings as ontocast serve, and the LLM settings
it validates at start-up. The check itself makes no LLM call; under
ONTOLOGY_CONTEXT_MODE=selected_vector_search_ontology, start-up may still
index the catalog with the configured embedding model. Start-up neither wipes
the vector partition nor loads seed directories, but, as ontocast serve
does, it writes the catalog it loaded back to the store unchanged and may
reindex it or prune vector entries for ontologies no longer in it. The
tenant options cannot be combined with --ontology-dir or --shapes-dir.
What is checked¶
| Finding | Meaning |
|---|---|
non_catalog_vocabulary |
a term the catalog does not define, whether in another namespace or missing from a namespace the catalog declares terms in |
unknown_term |
a term missing from a well-known vocabulary, or a term the catalog does not define in a placeholder namespace such as example.org; an error in both modes |
domain_violation |
a property used on a subject outside its declared domain |
functional_violation |
a functional property with several values |
untyped_value |
a plain value that would be valid typed (warning) |
invalid_literal |
a value that cannot be read as its datatype, or a language-tagged value on a numeric or temporal range |
temporal_range_mismatch |
a valid typed literal of the wrong type on a temporal range |
shacl |
a SHACL violation, when shapes are given |
untyped_instance, isolated_instance, silent_instance, dangling_reference, twin_labels |
instance hygiene |
catalog_subject, schema_in_facts |
schema statements in the facts graph |
vocabulary="strict" (the default) makes non_catalog_vocabulary an error;
"open" makes it a warning.
Instances¶
Instances are decided per IRI: an IRI subject is an instance unless it is a
class or property of the catalog, a term declared in the checked graph, or
under a well-known namespace. The catalog's own individuals (ex:Paris a
ex:City) are instances, and keep the types the catalog gives them. Pass instance_namespaces to restrict instances to given
namespaces.
Empty catalog¶
With no catalog the checks that need one are skipped and the report sets
catalog_empty; well-known-term checks and literal syntax still run.
The report¶
FactsCheckReport holds findings (errors first, capped by max_findings),
findings_total, complete counts by kind and severity, metrics
(triples, instances, isolated, untyped, twin labels), shacl_evaluated and
catalog_empty. ontocast check --json prints it as JSON.