Skip to content

graflo.architecture.schema.semantics

Optional grounding of schema elements in external vocabularies.

Purely additive and never consulted at execution time: identity, storage naming and ingestion behave identically whether or not these blocks are present. Their audience is the reader — human or agent — deciding what a type means before deciding what to ask about it.

Serialized through the gf: meta-ontology, reusing skos:exactMatch and skos:altLabel rather than minting GraFlo-specific equivalents.

FieldSemantics

Bases: Semantics

Anchors for a property, which additionally may carry a unit.

Separate from :class:Semantics on purpose: a unit on a vertex or an edge is meaningless, and because these models forbid extra keys, the split makes unit: on a vertex a validation error without any custom validator.

Source code in graflo/architecture/schema/semantics.py 
39
40
41
42
43
44
45
46
47
48
49
50
class FieldSemantics(Semantics):
    """Anchors for a property, which additionally may carry a unit.

    Separate from :class:`Semantics` on purpose: a unit on a vertex or an edge is
    meaningless, and because these models forbid extra keys, the split makes
    ``unit:`` on a vertex a validation error without any custom validator.
    """

    unit: str | None = PydanticField(
        default=None,
        description="Unit of measure as a UCUM or QUDT token, e.g. ``m/s``, ``USD``.",
    )

Semantics

Bases: ConfigBaseModel

External-vocabulary anchors for a vertex, edge, or whole schema.

Source code in graflo/architecture/schema/semantics.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
class Semantics(ConfigBaseModel):
    """External-vocabulary anchors for a vertex, edge, or whole schema."""

    iri: str | None = PydanticField(
        default=None,
        description=(
            "IRI of the concept this element denotes, e.g. "
            "``https://schema.org/Person``."
        ),
    )
    exact_match: list[str] = PydanticField(
        default_factory=list,
        description="IRIs asserted equivalent to this element (``skos:exactMatch``).",
    )
    synonyms: list[str] = PydanticField(
        default_factory=list,
        description="Alternative labels an agent may encounter (``skos:altLabel``).",
    )