Skip to content

ontocast.onto.identity

Ontology identity as types: the id, the IRI, and the pair.

An ontology's identity is minted by code, never written by a model: the model proposes an ontology_id (and a title and description), and the IRI is <CURRENT_DOMAIN>/<ontology_id>. Everything that would let two spellings of one ontology coexist -- a fragment on the IRI, a standard prefix bound to anything but its standard namespace, an id that collides with the document or facts namespaces -- is refused here, at construction; an empty fragment is dropped.

An id is also the prefix an ontology's terms are shown under, so a standard prefix is a binding, not a name: sosa may name the ontology whose namespace is http://www.w3.org/ns/sosa/ (W3C SOSA, adopted from its file) and nothing else, and never an ontology minted here.

Attributes

LIBRARY_ONTOLOGY_IDS = frozenset({'cd', 'doc', 'facts', 'oc', 'ontocast'}) module-attribute

MintedOntologyId = Annotated[str, AfterValidator(validate_minted_ontology_id)] module-attribute

ONTOLOGY_ID_PATTERN = re.compile('^[a-z][a-z0-9_-]{1,31}$') module-attribute

OntologyId = Annotated[str, AfterValidator(validate_ontology_id)] module-attribute

OntologyIri = Annotated[str, AfterValidator(validate_ontology_iri)] module-attribute

STANDARD_PREFIX_NAMESPACES = _standard_prefix_namespaces() module-attribute

Classes

OntologyIdentity

Bases: BaseModel

What names an ontology: its id, its IRI, and how it describes itself.

namespace is where its terms live: an existing ontology's own, else <iri>#, where a new ontology's terms are minted.

Source code in ontocast/onto/identity.py
class OntologyIdentity(BaseModel):
    """What names an ontology: its id, its IRI, and how it describes itself.

    ``namespace`` is where its terms live: an existing ontology's own, else
    ``<iri>#``, where a new ontology's terms are minted.
    """

    model_config = ConfigDict(frozen=True)

    ontology_id: OntologyId
    iri: OntologyIri
    title: str = Field(min_length=1, max_length=200)
    description: str = Field(default="", max_length=2000)
    namespace: str = Field(default="")

    @model_validator(mode="before")
    @classmethod
    def _default_namespace(cls, data: Any) -> Any:
        if isinstance(data, dict) and not data.get("namespace") and data.get("iri"):
            iri = validate_ontology_iri(str(data["iri"]))
            data = {
                **data,
                "namespace": normalize_namespace_iri(iri, context="ontology"),
            }
        return data

    @model_validator(mode="after")
    def _prefix_matches_namespace(self) -> OntologyIdentity:
        check_prefix_binding(self.ontology_id, self.namespace)
        return self

Attributes

description = Field(default='', max_length=2000) class-attribute instance-attribute
iri instance-attribute
model_config = ConfigDict(frozen=True) class-attribute instance-attribute
namespace = Field(default='') class-attribute instance-attribute
ontology_id instance-attribute
title = Field(min_length=1, max_length=200) class-attribute instance-attribute

OntologyVersionRecord

Bases: VersionRef

A version a run wrote: created as a root, or updated from its priors.

Source code in ontocast/onto/identity.py
class OntologyVersionRecord(VersionRef):
    """A version a run wrote: created as a root, or updated from its priors."""

    ontology_id: str
    version: str
    prior_version_iris: list[str] = Field(default_factory=list)
    role: Literal["created", "updated"]

Attributes

ontology_id instance-attribute
prior_version_iris = Field(default_factory=list) class-attribute instance-attribute
role instance-attribute
version instance-attribute

VersionRef

Bases: BaseModel

One stored version of one ontology.

Source code in ontocast/onto/identity.py
class VersionRef(BaseModel):
    """One stored version of one ontology."""

    model_config = ConfigDict(frozen=True)

    iri: str
    version_iri: str

    @property
    def key(self) -> str:
        return split_version_iri(self.version_iri)[1]

Attributes

iri instance-attribute
key property
model_config = ConfigDict(frozen=True) class-attribute instance-attribute
version_iri instance-attribute

Functions:

check_prefix_binding(ontology_id, namespace)

Refuse a standard prefix as the id of an ontology outside its namespace.

Raises:

Type Description
ValueError

ontology_id is a standard prefix and namespace is not the namespace it stands for.

Source code in ontocast/onto/identity.py
def check_prefix_binding(ontology_id: str, namespace: str) -> None:
    """Refuse a standard prefix as the id of an ontology outside its namespace.

    Raises:
        ValueError: ``ontology_id`` is a standard prefix and ``namespace`` is not
            the namespace it stands for.
    """
    expected = STANDARD_PREFIX_NAMESPACES.get(ontology_id)
    if expected is not None and namespace not in expected:
        raise ValueError(
            f"ontology_id {ontology_id!r} is a standard prefix for "
            f"{' or '.join(sorted(expected))}; this ontology's namespace is "
            f"{namespace or '(none)'!s}, so it needs another id"
        )

mint_ontology_iri(current_domain, ontology_id)

The IRI of the ontology ontology_id under current_domain.

Source code in ontocast/onto/identity.py
def mint_ontology_iri(current_domain: str, ontology_id: str) -> str:
    """The IRI of the ontology ``ontology_id`` under ``current_domain``."""
    return validate_ontology_iri(
        f"{validate_current_domain(current_domain)}/"
        f"{validate_minted_ontology_id(ontology_id)}"
    )

split_version_iri(version_iri)

(ontology IRI, version key) of a version IRI.

Raises:

Type Description
ValueError

version_iri has no fragment, or more than one.

Source code in ontocast/onto/identity.py
def split_version_iri(version_iri: str) -> tuple[str, str]:
    """``(ontology IRI, version key)`` of a version IRI.

    Raises:
        ValueError: ``version_iri`` has no fragment, or more than one.
    """
    if version_iri.count("#") != 1:
        raise ValueError(f"not a version IRI (expected <iri>#<key>): {version_iri!r}")
    iri, key = version_iri.split("#", 1)
    if not key:
        raise ValueError(f"version IRI has an empty key: {version_iri!r}")
    return validate_ontology_iri(iri), key

validate_current_domain(value)

The IRI stem ontology and document IRIs are minted under.

Source code in ontocast/onto/identity.py
def validate_current_domain(value: str) -> str:
    """The IRI stem ontology and document IRIs are minted under."""
    text = value.strip()
    parts = urlsplit(text)
    if parts.scheme not in ("http", "https") or not parts.netloc:
        raise ValueError(f"CURRENT_DOMAIN {value!r} must be an absolute http(s) IRI")
    if "#" in text or parts.query or text.endswith("/"):
        raise ValueError(
            f"CURRENT_DOMAIN {value!r} must carry no fragment, no query and no "
            "trailing '/'"
        )
    return text

validate_minted_ontology_id(value)

An id for an ontology minted under CURRENT_DOMAIN: no standard prefix.

A minted ontology's namespace is never a standard one, so a standard prefix would show its terms under a prefix that already means something else.

Source code in ontocast/onto/identity.py
def validate_minted_ontology_id(value: str) -> str:
    """An id for an ontology minted under ``CURRENT_DOMAIN``: no standard prefix.

    A minted ontology's namespace is never a standard one, so a standard prefix
    would show its terms under a prefix that already means something else.
    """
    cleaned = validate_ontology_id(value)
    if cleaned in STANDARD_PREFIX_NAMESPACES:
        raise ValueError(
            f"ontology_id {cleaned!r} is reserved (a standard prefix); choose "
            "another id"
        )
    return cleaned

validate_ontology_id(value)

Return value as an ontology id, or raise ValueError.

Only whitespace is stripped and case folded; any other repair would let two proposals that differ in spelling land on one id. A standard prefix passes here: whether it may name an ontology depends on the ontology's namespace (:func:check_prefix_binding).

Source code in ontocast/onto/identity.py
def validate_ontology_id(value: str) -> str:
    """Return ``value`` as an ontology id, or raise ``ValueError``.

    Only whitespace is stripped and case folded; any other repair would let two
    proposals that differ in spelling land on one id. A standard prefix passes
    here: whether it may name an ontology depends on the ontology's namespace
    (:func:`check_prefix_binding`).
    """
    cleaned = value.strip().lower()
    if not ONTOLOGY_ID_PATTERN.match(cleaned):
        raise ValueError(
            f"ontology_id {value!r} must match {ONTOLOGY_ID_PATTERN.pattern}: "
            "lowercase letters, digits, '_' or '-', 2-32 characters, starting "
            "with a letter"
        )
    if cleaned in LIBRARY_ONTOLOGY_IDS:
        raise ValueError(
            f"ontology_id {cleaned!r} is reserved (a namespace the library itself uses)"
        )
    return cleaned

validate_ontology_iri(value)

Return value as a canonical ontology IRI, or raise ValueError.

An absolute http(s) IRI with no fragment: the version graph of each version is <iri>#<key>, so the IRI itself cannot carry a #. An empty fragment (…/prov#, common in published vocabularies) names the same document and is dropped; any other fragment is refused.

Source code in ontocast/onto/identity.py
def validate_ontology_iri(value: str) -> str:
    """Return ``value`` as a canonical ontology IRI, or raise ``ValueError``.

    An absolute ``http(s)`` IRI with no fragment: the version graph of each
    version is ``<iri>#<key>``, so the IRI itself cannot carry a ``#``. An
    empty fragment (``…/prov#``, common in published vocabularies) names the
    same document and is dropped; any other fragment is refused.
    """
    text = value.strip()
    if text.endswith("#"):
        text = text[:-1]
    parts = urlsplit(text)
    if parts.scheme not in ("http", "https") or not parts.netloc:
        raise ValueError(f"ontology IRI {value!r} must be an absolute http(s) IRI")
    if "#" in text or parts.query:
        raise ValueError(
            f"ontology IRI {value!r} must carry no fragment and no query: "
            "versions are addressed as <iri>#<key>"
        )
    if any(char.isspace() for char in text):
        raise ValueError(f"ontology IRI {value!r} must not contain whitespace")
    return text

version_iri_for(iri, key)

The named graph holding version key of the ontology iri.

Source code in ontocast/onto/identity.py
def version_iri_for(iri: str, key: str) -> str:
    """The named graph holding version ``key`` of the ontology ``iri``."""
    return f"{iri}#{key}"