Skip to content

ontocast.onto.well_known

The well-known vocabularies a facts render may use beside the catalog.

Every facts vocabulary mode admits them: the W3C and DCMI core, FOAF, schema.org and QUDT. A term of one of them must exist in it. Term lists come from rdflib's bundled namespace definitions; RDF 1.2 terms rdflib does not list yet are added here. The QUDT schema, QUDT unit and vCard lists ship as data in vocabularies/. QUDT quantity kinds are admitted by namespace, without a list.

Some vocabularies also name the classes of structured values (a quantity, an amount): a node of such a class belongs to the statement that carries it.

Attributes

QUDT_UNIT_NAMESPACE = 'http://qudt.org/vocab/unit/' module-attribute

WELL_KNOWN_VOCABULARIES = (_vocabulary('rdf', 'RDF', RDF, extra=_RDF_12_TERMS), _vocabulary('rdfs', 'RDF Schema', RDFS), _vocabulary('owl', 'OWL', OWL), _vocabulary('xsd', 'XML Schema datatypes', XSD), _vocabulary('skos', 'SKOS', SKOS), _vocabulary('dcterms', 'DCMI Metadata Terms', DCTERMS, temporal_properties=('date', 'created', 'issued', 'modified')), _vocabulary('dc', 'Dublin Core elements', DC), _vocabulary('prov', 'PROV-O', PROV, datatype_ranges={name: 'dateTime' for name in ('atTime', 'startedAtTime', 'endedAtTime', 'generatedAtTime', 'invalidatedAtTime')}), _vocabulary('sosa', 'SOSA', SOSA, datatype_ranges={'resultTime': 'dateTime'}, temporal_properties=('phenomenonTime',), statement_classes=('Observation', 'Actuation', 'Sampling'), statement_properties={'hasFeatureOfInterest': 'has feature of interest', 'observedProperty': 'observed property', 'hasResult': 'has result'}, subject_links={'hasFeatureOfInterest': 'forward', 'isFeatureOfInterestOf': 'inverse'}, object_pairs={'hasSimpleResult': 'hasResult'}), _vocabulary('ssn', 'SSN', SSN), _vocabulary('time', 'OWL-Time', TIME, datatype_ranges={'inXSDDate': 'date', 'inXSDDateTime': 'dateTime', 'inXSDDateTimeStamp': 'dateTimeStamp', 'inXSDgYear': 'gYear', 'inXSDgYearMonth': 'gYearMonth'}, temporal_properties=('hasTime', 'hasBeginning', 'hasEnd', 'inside')), _vocabulary('csvw', 'CSVW', CSVW), _vocabulary('dcat', 'DCAT', DCAT), _vocabulary('org', 'the Organization Ontology', ORG), _listed('vcard', 'vCard', 'http://www.w3.org/2006/vcard/ns#', 'vcard.txt'), _vocabulary('foaf', 'FOAF', FOAF), _vocabulary('schema', 'schema.org', SDO, also=('http://schema.org/',), value_classes=('StructuredValue', 'QuantitativeValue', 'PropertyValue', 'MonetaryAmount'), temporal_properties=('startDate', 'endDate', 'datePublished', 'dateCreated', 'dateModified')), _listed('qudt', 'QUDT', 'http://qudt.org/schema/qudt/', 'qudt_schema.txt', value_classes=('QuantityValue',)), _listed('unit', 'QUDT units', QUDT_UNIT_NAMESPACE, 'qudt_units.txt'), _by_namespace('quantitykind', 'QUDT quantity kinds', 'http://qudt.org/vocab/quantitykind/')) module-attribute

WellKnownRole = Literal['class', 'property', 'datatype'] module-attribute

__all__ = ['QUDT_UNIT_NAMESPACE', 'WELL_KNOWN_VOCABULARIES', 'WellKnownRole', 'WellKnownVocabulary', 'is_listed_unit', 'is_well_known_term', 'well_known_by_local_name', 'well_known_role', 'well_known_namespaces', 'well_known_object_pairs', 'well_known_prompt_list', 'well_known_terms', 'well_known_datatype_ranges', 'well_known_statement_classes', 'well_known_statement_properties', 'well_known_subject_links', 'well_known_temporal_properties', 'well_known_value_classes', 'well_known_vocabulary'] module-attribute

Classes

WellKnownVocabulary

Bases: BaseModel

One well-known vocabulary.

Attributes:

Name Type Description
prefix str

The prefix the prompt shows for it.

title str

Its name, for messages.

namespaces tuple[str, ...]

Its namespace IRIs; the first is canonical.

terms frozenset[str] | None

Local names of its terms, or None when it is admitted by namespace (no term list is bundled).

value_classes frozenset[str]

Local names of its classes of structured values.

datatype_ranges dict[str, str]

Local name of a property -> local name of the XSD datatype its published rdfs:range declares, for the date and time properties the facts repairs check literals against.

temporal_properties frozenset[str]

Local names of its properties whose object is a time, a temporal entity or a date literal; those in datatype_ranges count without being listed here.

statement_classes frozenset[str]

Local names of its classes whose instances are statements about something else (an observation of a feature of interest): one is a fact only with its subject.

statement_properties dict[str, str]

Local name -> label of the properties a statement takes (its subject, what it observed, its result), shown beside a catalog's statement classes.

subject_links dict[str, Literal['forward', 'inverse']]

Local name -> direction of the properties that link a statement and what it is about: forward runs from the statement to its subject, inverse from the subject.

object_pairs dict[str, str]

Local name of a datatype property -> local name of the object property the vocabulary gives for the same relation when the object is a node.

Source code in ontocast/onto/well_known.py
class WellKnownVocabulary(BaseModel):
    """One well-known vocabulary.

    Attributes:
        prefix: The prefix the prompt shows for it.
        title: Its name, for messages.
        namespaces: Its namespace IRIs; the first is canonical.
        terms: Local names of its terms, or ``None`` when it is admitted by
            namespace (no term list is bundled).
        value_classes: Local names of its classes of structured values.
        datatype_ranges: Local name of a property -> local name of the XSD
            datatype its published ``rdfs:range`` declares, for the date and
            time properties the facts repairs check literals against.
        temporal_properties: Local names of its properties whose object is a
            time, a temporal entity or a date literal; those in
            ``datatype_ranges`` count without being listed here.
        statement_classes: Local names of its classes whose instances are
            statements about something else (an observation of a feature of
            interest): one is a fact only with its subject.
        statement_properties: Local name -> label of the properties a
            statement takes (its subject, what it observed, its result),
            shown beside a catalog's statement classes.
        subject_links: Local name -> direction of the properties that link a
            statement and what it is about: ``forward`` runs from the
            statement to its subject, ``inverse`` from the subject.
        object_pairs: Local name of a datatype property -> local name of the
            object property the vocabulary gives for the same relation when
            the object is a node.
    """

    model_config = ConfigDict(frozen=True)

    prefix: str
    title: str
    namespaces: tuple[str, ...]
    terms: frozenset[str] | None
    value_classes: frozenset[str] = frozenset()
    datatype_ranges: dict[str, str] = Field(default_factory=dict)
    temporal_properties: frozenset[str] = frozenset()
    statement_classes: frozenset[str] = frozenset()
    statement_properties: dict[str, str] = Field(default_factory=dict)
    subject_links: dict[str, Literal["forward", "inverse"]] = Field(
        default_factory=dict
    )
    object_pairs: dict[str, str] = Field(default_factory=dict)

    def has_term(self, local_name: str) -> bool:
        """Whether ``local_name`` is a term of this vocabulary."""
        if self.terms is None:
            return True
        if self.prefix == "rdf" and _CONTAINER_MEMBER.fullmatch(local_name):
            return True
        return local_name in self.terms

Attributes

datatype_ranges = Field(default_factory=dict) class-attribute instance-attribute
model_config = ConfigDict(frozen=True) class-attribute instance-attribute
namespaces instance-attribute
object_pairs = Field(default_factory=dict) class-attribute instance-attribute
prefix instance-attribute
statement_classes = frozenset() class-attribute instance-attribute
statement_properties = Field(default_factory=dict) class-attribute instance-attribute
temporal_properties = frozenset() class-attribute instance-attribute
terms instance-attribute
title instance-attribute
value_classes = frozenset() class-attribute instance-attribute

Methods:

has_term(local_name)

Whether local_name is a term of this vocabulary.

Source code in ontocast/onto/well_known.py
def has_term(self, local_name: str) -> bool:
    """Whether ``local_name`` is a term of this vocabulary."""
    if self.terms is None:
        return True
    if self.prefix == "rdf" and _CONTAINER_MEMBER.fullmatch(local_name):
        return True
    return local_name in self.terms

Functions:

is_listed_unit(iri)

Whether iri is a unit of the shipped QUDT unit list.

Source code in ontocast/onto/well_known.py
def is_listed_unit(iri: str) -> bool:
    """Whether ``iri`` is a unit of the shipped QUDT unit list."""
    return iri.startswith(QUDT_UNIT_NAMESPACE) and is_well_known_term(iri) is True

is_well_known_term(iri)

Whether iri is a term of its well-known vocabulary.

Returns:

Type Description
bool | None

None when iri is in no well-known namespace; otherwise whether

bool | None

the vocabulary has the term (always true for one admitted by

bool | None

namespace).

Source code in ontocast/onto/well_known.py
def is_well_known_term(iri: str) -> bool | None:
    """Whether ``iri`` is a term of its well-known vocabulary.

    Returns:
        ``None`` when ``iri`` is in no well-known namespace; otherwise whether
        the vocabulary has the term (always true for one admitted by
        namespace).
    """
    namespace, local_name = _split(iri)
    vocabulary = _index().get(namespace)
    if vocabulary is None:
        return None
    return vocabulary.has_term(local_name)

well_known_by_local_name(local_name, role)

Well-known terms of role named local_name, ignoring case.

In the order of :data:WELL_KNOWN_VOCABULARIES; vocabularies admitted by namespace have no term list and never match.

Source code in ontocast/onto/well_known.py
def well_known_by_local_name(local_name: str, role: WellKnownRole) -> tuple[str, ...]:
    """Well-known terms of ``role`` named ``local_name``, ignoring case.

    In the order of :data:`WELL_KNOWN_VOCABULARIES`; vocabularies admitted by
    namespace have no term list and never match.
    """
    return tuple(
        iri
        for iri in _by_local_name().get(local_name.casefold(), ())
        if well_known_role(iri) == role
    )

well_known_datatype_ranges() cached

Property IRI -> XSD datatype IRI, as the well-known vocabularies publish them.

Only the date and time properties are listed. Treat as read-only.

Source code in ontocast/onto/well_known.py
@cache
def well_known_datatype_ranges() -> dict[str, str]:
    """Property IRI -> XSD datatype IRI, as the well-known vocabularies publish them.

    Only the date and time properties are listed. Treat as read-only.
    """
    return {
        namespace + name: str(XSD) + datatype
        for vocabulary in WELL_KNOWN_VOCABULARIES
        for namespace in vocabulary.namespaces
        for name, datatype in vocabulary.datatype_ranges.items()
    }

well_known_namespaces()

Every namespace IRI of the well-known vocabularies.

Source code in ontocast/onto/well_known.py
def well_known_namespaces() -> tuple[str, ...]:
    """Every namespace IRI of the well-known vocabularies."""
    return tuple(_index())

well_known_object_pairs() cached

Datatype property IRI -> the object property IRI paired with it.

The pair states the same relation with a node as its object, so a node written on the datatype property belongs on the object property.

Source code in ontocast/onto/well_known.py
@cache
@cache
def well_known_object_pairs() -> dict[str, str]:
    """Datatype property IRI -> the object property IRI paired with it.

    The pair states the same relation with a node as its object, so a node
    written on the datatype property belongs on the object property.
    """
    return {
        namespace + datatype_property: namespace + object_property
        for vocabulary in WELL_KNOWN_VOCABULARIES
        for namespace in vocabulary.namespaces
        for datatype_property, object_property in vocabulary.object_pairs.items()
    }

well_known_prompt_list()

The vocabularies as the facts prompt names them: prefix: and IRI.

Source code in ontocast/onto/well_known.py
def well_known_prompt_list() -> str:
    """The vocabularies as the facts prompt names them: ``prefix:`` and IRI."""
    return ", ".join(
        f"`{vocabulary.prefix}:` <{vocabulary.namespaces[0]}>"
        for vocabulary in WELL_KNOWN_VOCABULARIES
    )

well_known_role(iri)

The kind of a well-known term, by the naming its vocabulary follows.

The well-known vocabularies capitalise their classes and not their properties; XSD's terms and a few RDF and OWL literal types are datatypes.

Returns:

Type Description
WellKnownRole | None

None for an IRI outside the well-known vocabularies, a term its

WellKnownRole | None

vocabulary does not have, or an individual (QUDT units and quantity

WellKnownRole | None

kinds, rdf:nil).

Source code in ontocast/onto/well_known.py
def well_known_role(iri: str) -> WellKnownRole | None:
    """The kind of a well-known term, by the naming its vocabulary follows.

    The well-known vocabularies capitalise their classes and not their
    properties; XSD's terms and a few RDF and OWL literal types are
    datatypes.

    Returns:
        ``None`` for an IRI outside the well-known vocabularies, a term its
        vocabulary does not have, or an individual (QUDT units and quantity
        kinds, ``rdf:nil``).
    """
    namespace, local_name = _split(iri)
    vocabulary = _index().get(namespace)
    if (
        vocabulary is None
        or not local_name
        or vocabulary.prefix in _INDIVIDUAL_VOCABULARIES
        or not vocabulary.has_term(local_name)
        or iri in _INDIVIDUAL_TERMS
    ):
        return None
    if vocabulary.prefix == "xsd" or iri in _DATATYPE_TERMS:
        return "datatype"
    return "class" if local_name[0].isupper() else "property"

well_known_statement_classes() cached

Classes of the well-known vocabularies whose instances are statements.

An instance of one (or of a subclass) is about something else, its feature of interest; without that link it states a value of nothing.

Source code in ontocast/onto/well_known.py
@cache
def well_known_statement_classes() -> frozenset[str]:
    """Classes of the well-known vocabularies whose instances are statements.

    An instance of one (or of a subclass) is about something else, its
    feature of interest; without that link it states a value of nothing.
    """
    return frozenset(
        namespace + name
        for vocabulary in WELL_KNOWN_VOCABULARIES
        for namespace in vocabulary.namespaces
        for name in vocabulary.statement_classes
    )

well_known_statement_properties() cached

Property IRI -> label of the properties a well-known statement takes.

Source code in ontocast/onto/well_known.py
@cache
def well_known_statement_properties() -> dict[str, str]:
    """Property IRI -> label of the properties a well-known statement takes."""
    return {
        vocabulary.namespaces[0] + name: label
        for vocabulary in WELL_KNOWN_VOCABULARIES
        for name, label in vocabulary.statement_properties.items()
    }

The well-known properties linking a statement and its subject, as IRIs.

Returns:

Type Description
frozenset[str]

(forward, inverse): those running from the statement to its

frozenset[str]

subject, and those running from the subject to the statement.

Source code in ontocast/onto/well_known.py
@cache
def well_known_subject_links() -> tuple[frozenset[str], frozenset[str]]:
    """The well-known properties linking a statement and its subject, as IRIs.

    Returns:
        ``(forward, inverse)``: those running from the statement to its
        subject, and those running from the subject to the statement.
    """
    links = [
        (vocabulary.namespaces[0] + name, direction)
        for vocabulary in WELL_KNOWN_VOCABULARIES
        for name, direction in vocabulary.subject_links.items()
    ]
    return (
        frozenset(iri for iri, direction in links if direction == "forward"),
        frozenset(iri for iri, direction in links if direction == "inverse"),
    )

well_known_temporal_properties()

Property IRIs of the well-known vocabularies whose object is a time.

Source code in ontocast/onto/well_known.py
def well_known_temporal_properties() -> frozenset[str]:
    """Property IRIs of the well-known vocabularies whose object is a time."""
    return frozenset(
        namespace + name
        for vocabulary in WELL_KNOWN_VOCABULARIES
        for namespace in vocabulary.namespaces
        for name in (*vocabulary.temporal_properties, *vocabulary.datatype_ranges)
    )

well_known_terms(namespace)

The term IRIs of the vocabulary at namespace, spelled in it.

Empty for a namespace that is not well-known or is admitted by namespace.

Source code in ontocast/onto/well_known.py
def well_known_terms(namespace: str) -> set[str]:
    """The term IRIs of the vocabulary at ``namespace``, spelled in it.

    Empty for a namespace that is not well-known or is admitted by namespace.
    """
    vocabulary = _index().get(namespace)
    if vocabulary is None or vocabulary.terms is None:
        return set()
    return {namespace + name for name in vocabulary.terms}

well_known_value_classes() cached

The classes of structured values the well-known vocabularies name, as IRIs.

A node of one of them (or of a subclass) is a value: it belongs to the statement that carries it and is never a fact on its own.

Source code in ontocast/onto/well_known.py
@cache
def well_known_value_classes() -> frozenset[str]:
    """The classes of structured values the well-known vocabularies name, as IRIs.

    A node of one of them (or of a subclass) is a value: it belongs to the
    statement that carries it and is never a fact on its own.
    """
    return frozenset(
        namespace + name
        for vocabulary in WELL_KNOWN_VOCABULARIES
        for namespace in vocabulary.namespaces
        for name in vocabulary.value_classes
    )

well_known_vocabulary(iri)

The well-known vocabulary iri belongs to, if any.

Source code in ontocast/onto/well_known.py
def well_known_vocabulary(iri: str) -> WellKnownVocabulary | None:
    """The well-known vocabulary ``iri`` belongs to, if any."""
    return _index().get(_split(iri)[0])