ontocast.tool.facts_validation.terms¶
Catalog term inventory, namespace closure rules, and alias candidates.
What the catalog declares versus merely references decides which
namespaces the term checks may treat as closed; ValidationPolicy carries
the deployment-level exemptions every check honours.
Attributes¶
logger = logging.getLogger(__name__)
module-attribute
¶
Classes¶
CatalogRoles
¶
What the whole catalog says each term is, read once per catalog state.
A unit sees a retrieved snapshot; the role of a term (property or class) and a class's place in the hierarchy are read from every held ontology, so a term the snapshot omits is still known for what it is.
Attributes:
| Name | Type | Description |
|---|---|---|
properties |
Terms the catalog states are properties. |
|
classes |
Terms the catalog states are classes. |
|
hierarchy |
The catalog's subclass statements, for closures. |
|
axioms |
The catalog's domains, ranges, listed classes and the types of its terms, with the hierarchy. |
|
datatype_ranges |
Each property's declared |
Source code in ontocast/tool/facts_validation/terms.py
449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 | |
Attributes¶
axioms = axioms if axioms is not None else RDFGraph()
instance-attribute
¶
classes = classes
instance-attribute
¶
datatype_ranges = datatype_ranges or {}
instance-attribute
¶
hierarchy = hierarchy if hierarchy is not None else RDFGraph()
instance-attribute
¶
properties = properties
instance-attribute
¶
Methods:¶
__init__(properties=frozenset(), classes=frozenset(), hierarchy=None, datatype_ranges=None, axioms=None)
¶
Source code in ontocast/tool/facts_validation/terms.py
classes_under(base)
¶
base and every catalog class whose supertypes meet it.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
base
|
frozenset[str]
|
Anchor classes, such as the classes of structured values
(:func: |
required |
Source code in ontocast/tool/facts_validation/terms.py
declared_ranges()
¶
Each property's declared XSD ranges: the catalog's and the well-known.
Read once per catalog state; a unit adds only its snapshot's.
Source code in ontocast/tool/facts_validation/terms.py
of(graphs)
classmethod
¶
The roles and hierarchy stated across graphs.
Source code in ontocast/tool/facts_validation/terms.py
subject_contract(value_base)
¶
The :class:SubjectContract of this catalog.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value_base
|
frozenset[str]
|
The value classes to anchor on (:func: |
required |
Source code in ontocast/tool/facts_validation/terms.py
subject_links()
¶
The properties linking a statement and its subject, each direction.
The well-known ones, every catalog sub-property of one, and every catalog inverse of one in the other direction.
Returns:
| Type | Description |
|---|---|
tuple[frozenset[str], frozenset[str]]
|
|
Source code in ontocast/tool/facts_validation/terms.py
with_axioms(graph)
¶
graph together with the catalog's axioms, as a new graph.
A unit's snapshot may keep a property's domain and drop its range, or a class without its place in the hierarchy; domain and range repairs read this union so the answer does not depend on what retrieval kept.
Source code in ontocast/tool/facts_validation/terms.py
SubjectContract
¶
Bases: BaseModel
What makes a statement name its subject, over the whole catalog.
Attributes:
| Name | Type | Description |
|---|---|---|
statement_classes |
frozenset[str]
|
Classes whose instances are statements about something else (an observation), with every catalog class under one. |
value_classes |
frozenset[str]
|
Classes whose instances are values, likewise. |
forward |
frozenset[str]
|
Properties running from a statement to its subject. |
inverse |
frozenset[str]
|
Properties running from a subject to a statement. |
Source code in ontocast/tool/facts_validation/terms.py
Attributes¶
forward = frozenset()
class-attribute
instance-attribute
¶
inverse = frozenset()
class-attribute
instance-attribute
¶
model_config = {'frozen': True}
class-attribute
instance-attribute
¶
statement_classes = frozenset()
class-attribute
instance-attribute
¶
value_classes = frozenset()
class-attribute
instance-attribute
¶
ValidationPolicy
¶
Bases: BaseModel
Deployment-level exemptions and vocabulary for deterministic validation.
One object instead of a parameter per concern: the namespaces a deployment shares across catalogs, the sanctioned quantity fallback vocabulary, and the code predicates — everything the term checks must never flag, because configuration explicitly blessed it.
Source code in ontocast/tool/facts_validation/terms.py
Attributes¶
additional_standard_namespaces = ()
class-attribute
instance-attribute
¶
code_predicates = ()
class-attribute
instance-attribute
¶
contract_exempt_terms = ()
class-attribute
instance-attribute
¶
domain_adherence_min_share = 0.15
class-attribute
instance-attribute
¶
domain_adherence_min_terms = 4
class-attribute
instance-attribute
¶
numeric_identifier_guard = False
class-attribute
instance-attribute
¶
quantity_fallback_vocabulary = None
class-attribute
instance-attribute
¶
vocabulary = 'strict'
class-attribute
instance-attribute
¶
Methods:¶
exempt_terms(*graphs)
¶
Exact IRIs configuration blessed: fallback vocabulary, code predicates, and the shapes-contract terms.
Source code in ontocast/tool/facts_validation/terms.py
standard_namespaces()
¶
Namespaces no catalog owns: the meta-vocabularies, the well-known
vocabularies (:mod:ontocast.onto.well_known) and the configured
ones. A term of a well-known vocabulary must still exist in it.
Source code in ontocast/tool/facts_validation/terms.py
Functions:¶
build_surface_index(ontology_graph, code_predicates=())
¶
Map exact catalog surface forms to the IRIs declaring them.
Case-sensitive and exact: these are codes and names a model may have
transcribed verbatim ("d", "meV", "CsPbBr3"), not free text to
be fuzzy-matched. A form claimed by more than one IRI stays in the index and
is rejected at lookup time — an ambiguous code is not a repairable one.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ontology_graph
|
RDFGraph | None
|
Merged ontology context to index. |
required |
code_predicates
|
Sequence[str]
|
Extra code-bearing predicates (UCUM codes, symbols, notations) on top of the standard name predicates. |
()
|
Returns:
| Type | Description |
|---|---|
dict[str, set[str]]
|
Surface form -> set of IRIs declaring it. |
Source code in ontocast/tool/facts_validation/terms.py
catalog_term_evidence(ontology_graph)
¶
Catalog terms with property evidence and with class evidence.
Only what the catalog states is used: explicit property/class typing,
a domain or a range (rdfs or schema:*Includes, property evidence), and
rdfs:subClassOf / rdf:type-object position (class evidence). A
term may land in both sets; :func:_catalog_term_roles drops those.
Source code in ontocast/tool/facts_validation/terms.py
collect_catalog_terms(ontology_graph)
¶
All IRIs appearing anywhere in the ontology context.
Source code in ontocast/tool/facts_validation/terms.py
collect_declared_namespaces(ontology_graph)
¶
Namespaces the catalog declares terms in (subject-position IRIs).
The UNKNOWN_TERM check treats a namespace as closed — flagging members the
catalog does not list — only when the catalog actually declares terms
there. A namespace the catalog merely references (qudt:QuantityValue
in an rdfs:subClassOf, qudt:unit in an owl:onProperty) is an
external vocabulary the catalog borrows from, and the catalog is not an
authority on its membership. Treating referenced-only namespaces as closed
produced mandatory findings against canonical external properties
(qudt:numericValue), which repair renders then obeyed by deleting
correct data.
Source code in ontocast/tool/facts_validation/terms.py
concrete_types(graph, node, fact_namespaces)
¶
The asserted rdf:type objects of node that count as a type.
A type counts when it is an IRI outside fact_namespaces (a class
minted beside the instances is no class), not a schema metaclass
(rdfs:Class, owl:Class, rdf:Property, the OWL property
classes, owl:NamedIndividual) and not vacuous (owl:Thing,
rdfs:Resource, schema:Thing).
Source code in ontocast/tool/facts_validation/terms.py
declared_class_ranges(ontology_graph, *, source=None)
¶
Predicate -> the named classes its range names, datatypes left out.
Both rdfs:range and schema:rangeIncludes by default;
source="rdfs" keeps the entailing ones. A datatype range (XSD,
rdfs:Literal, a declared rdfs:Datatype) types a literal, not a
node, and is left out.
Source code in ontocast/tool/facts_validation/terms.py
domain_fits(subject, predicate, graph, ontology_graph)
¶
Whether subject's asserted types contradict no rdfs:domain of predicate.
The test :func:domain_violation_findings applies: only rdfs:domain
entails, so only it can be contradicted; a listed class is an expected
one.
Source code in ontocast/tool/facts_validation/terms.py
domain_fitting_properties(subject, obj, graph, ontology_graph, *, replacing, limit=8)
¶
Context properties that may link subject to obj in place of replacing.
A candidate declares a domain (rdfs:domain or schema:domainIncludes)
that the subject's asserted types fit, and no range the object's types
contradict; a literal object takes only a property with no class range.
Ranked by the local-name tokens shared with replacing, then by IRI.
Returns:
| Type | Description |
|---|---|
list[tuple[URIRef, set[URIRef]]]
|
Up to |
Source code in ontocast/tool/facts_validation/terms.py
expand_vocabulary_terms(vocabulary, *graphs)
¶
Expand configured vocabulary terms (CURIEs or full IRIs) to IRI strings.
CURIEs are expanded against the prefix bindings of every graph given, in order; a CURIE whose prefix no graph binds is dropped rather than guessed.
Source code in ontocast/tool/facts_validation/terms.py
fact_instances(graph, fact_namespaces)
¶
The instances a facts graph asserts.
An instance is a URIRef in one of fact_namespaces that occurs as a
subject, or as the IRI object of a triple other than rdf:type,
owl:sameAs. Blank nodes are never instances, and neither are the
nodes the pipeline mints: chunks, reifiers and the document node
(:mod:ontocast.onto.scaffolding). Triples touching a chunk or reifier
are skipped, whatever their vocabulary.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
graph
|
RDFGraph
|
Facts graph for one unit or the aggregated document. |
required |
fact_namespaces
|
Sequence[str]
|
Namespaces holding minted instances. |
required |
Returns:
| Type | Description |
|---|---|
set[URIRef]
|
set[URIRef]: The instances, in no particular order. |
Source code in ontocast/tool/facts_validation/terms.py
is_value_node(graph, node, value_classes)
¶
Whether a type of node is a value class (see :meth:CatalogRoles.value_classes).
Source code in ontocast/tool/facts_validation/terms.py
link_properties(node, graph, ontology_graph, *, limit=8)
¶
Context object properties that may link node to another instance.
A property qualifies with node as its subject when its declared domain
(rdfs:domain or schema:domainIncludes) fits node's asserted
types and it has a class range; as its object when its class range fits
them. Ordered by IRI, subject direction first.
Returns:
| Type | Description |
|---|---|
list[tuple[URIRef, str]]
|
Up to |
list[tuple[URIRef, str]]
|
when |
Source code in ontocast/tool/facts_validation/terms.py
resolve_unique_surface(index, text)
¶
The single IRI declaring text as a surface form, if exactly one does.
Source code in ontocast/tool/facts_validation/terms.py
sole_listed_classes(ontology_graph, side, declared)
¶
Predicate -> the one class its schema:<side>Includes lists.
Listed classes are alternatives, so they entail nothing in general; a
predicate listing exactly one named class, and declaring no rdfs
counterpart, leaves one reading.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ontology_graph
|
RDFGraph
|
Ontology context. |
required |
side
|
Side
|
|
required |
declared
|
Mapping[URIRef, set[URIRef]]
|
The predicate's |
required |
Returns:
| Type | Description |
|---|---|
dict[URIRef, URIRef]
|
The sole listed class per predicate; datatypes are never a class. |
Source code in ontocast/tool/facts_validation/terms.py
superclass_closure(class_iri, ontology_graph)
¶
Asserted supertypes of class_iri, including itself.
Walks rdfs:subClassOf and steps through owl:equivalentClass
intersections, because a class defined only as an intersection
(LeadHalidePerovskite ≡ Perovskite ⊓ …) has no asserted subClassOf edge
to its genus and would otherwise look unrelated to it.
Source code in ontocast/tool/facts_validation/terms.py
types_compatible(asserted, declared, ontology_graph, *, described, closures)
¶
Whether a node typed asserted fits classes declared (a domain or range).
Compatible in either direction: an asserted type specializes a declared
class, or a declared class specializes an asserted type. None when the
context cannot decide: no declared class it places in a hierarchy
(described), or an asserted type it does not describe.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
asserted
|
set[URIRef]
|
The node's asserted types. |
required |
declared
|
set[URIRef]
|
The declared domain or range classes. |
required |
ontology_graph
|
RDFGraph
|
The ontology context. |
required |
described
|
set[URIRef]
|
:func: |
required |
closures
|
dict[URIRef, set[URIRef]]
|
Cache of :func: |
required |
Source code in ontocast/tool/facts_validation/terms.py
untyped_instances(graph, fact_namespaces)
¶
Instances of graph (:func:fact_instances) with no concrete type.
Returns:
| Type | Description |
|---|---|
list[URIRef]
|
list[URIRef]: The untyped instances, ordered by IRI. |
Source code in ontocast/tool/facts_validation/terms.py
value_class_base(configured, bindings)
¶
The well-known value classes plus the deployment's configured one.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
configured
|
dict[str, str] | None
|
|
required |
bindings
|
dict[str, str]
|
Prefix -> namespace, to expand a CURIE. |
required |