SHACL → entities

app.shacl_to_entities

SHACL → EntityShape descriptors for SPARQL build and GeoJSON decode.

Parallel to shacl_to_filters: both walk the same NodeShapes; this module projects EntityShape descriptors, not filter UI widgets. Instance data is filled later by SPARQL over compass.ttl.

EntityShape

Bases: BaseModel

One property descriptor projected from SHACL (not an instance).

get_shacl_property(g)

Yield every sh:property IRI of every NodeShape that has a sh:targetClass.

Parameters:

Name	Type	Description	Default
g	Graph	Merged ontology graph (shapes + data + vocab).	required

Yields:

Type	Description
URIRef	URIRef property-shape subjects, de-duplicated.

Source code in src/backend/app/shacl_to_entities.py

def get_shacl_property(g: Graph) -> Iterator[URIRef]:
    """Yield every sh:property IRI of every NodeShape that has a sh:targetClass.

    Args:
        g: Merged ontology graph (shapes + data + vocab).

    Yields:
        ``URIRef`` property-shape subjects, de-duplicated.
    """
    seen: set = set()
    for node_shape in g.subjects(SH.targetClass, None):
        for p in g.objects(node_shape, SH.property):
            if isinstance(p, URIRef) and p not in seen:
                seen.add(p)
                yield p

get_shacl_label(g, subject, predicate, lang)

Return a label in lang, falling back to English, then any available label.

Parameters:

Name	Type	Description	Default
g	Graph	Ontology graph.	required
subject	URIRef	Resource whose label is sought.	required
predicate	URIRef	Preferred label predicate (e.g. sh:name, rdfs:label).	required
lang	str	BCP 47 language tag.	required

Returns:

Type	Description
str	Best-matching label string, or the subject's local name as last resort.

Source code in src/backend/app/shacl_to_entities.py

def get_shacl_label(g: Graph, subject: URIRef, predicate: URIRef, lang: str) -> str:
    """Return a label in *lang*, falling back to English, then any available label.

    Args:
        g: Ontology graph.
        subject: Resource whose label is sought.
        predicate: Preferred label predicate (e.g. ``sh:name``, ``rdfs:label``).
        lang: BCP 47 language tag.

    Returns:
        Best-matching label string, or the subject's local name as last resort.
    """
    candidates = list(g.objects(subject, predicate))
    if predicate != SKOS.prefLabel:
        candidates += list(g.objects(subject, SKOS.prefLabel))

    for label in candidates:
        if isinstance(label, RDFLiteral) and label.language == lang:
            return str(label)
    for label in candidates:
        if isinstance(label, RDFLiteral) and label.language == "en":
            return str(label)
    if candidates:
        return str(candidates[0])
    return str(subject).split("#")[-1].split("/")[-1]

get_entity_shape_from_shacl(g)

Project SHACL property shapes into EntityShape descriptors for query and decode.

Parameters:

Name	Type	Description	Default
g	Graph	Merged ontology graph.	required

Returns:

Type	Description
list[EntityShape]	One EntityShape per filterable/display property (builtins skipped).

Source code in src/backend/app/shacl_to_entities.py

def get_entity_shape_from_shacl(g: Graph) -> list[EntityShape]:
    """Project SHACL property shapes into EntityShape descriptors for query and decode.

    Args:
        g: Merged ontology graph.

    Returns:
        One ``EntityShape`` per filterable/display property (builtins skipped).
    """
    fields: list[EntityShape] = []

    for property_node in get_shacl_property(g):
        path = g.value(property_node, SH.path)
        if path is None or path in BUILTIN_PATHS:
            continue

        path_str = str(path)
        datatype = g.value(property_node, SH.datatype)
        target_class = g.value(property_node, SH["class"])
        sh_in_list = list(g.objects(property_node, SH["in"]))
        node_kind = g.value(property_node, SH.nodeKind)
        max_count_val = g.value(property_node, SH.maxCount)

        one_per_language = (
            datatype == RDF.langString
            and str(g.value(property_node, SH.uniqueLang)).lower() == "true"
        )
        is_multi = not one_per_language and (
            max_count_val is None or int(str(max_count_val)) != 1
        )
        is_iri = (
            (node_kind is not None and str(node_kind) == str(SH.IRI))
            or target_class is not None
            or bool(sh_in_list)
        )

        category = _infer_category(datatype, is_iri)
        filter_type = _infer_filter_type(path, category, datatype)

        fields.append(
            EntityShape(
                id=path_str.rsplit("#", maxsplit=1)[-1].rsplit("/", maxsplit=1)[-1],
                path_iri=path_str,
                category=category,
                is_multi=is_multi,
                filter_type=filter_type,
                datatype=str(datatype) if datatype else None,
            )
        )

    return fields

_infer_category(datatype, is_iri)

Map SHACL datatype / IRI-ness to a SPARQL binding category.

Parameters:

Name	Type	Description	Default
datatype	Node | None	sh:datatype value, or None.	required
is_iri	bool	True when the property values are IRIs (class, nodeKind, or sh:in).	required

Returns:

Type	Description
PropertyCategory	Category string consumed by the SPARQL builder and GeoJSON translator.

Source code in src/backend/app/shacl_to_entities.py

def _infer_category(datatype: Node | None, is_iri: bool) -> PropertyCategory:
    """Map SHACL datatype / IRI-ness to a SPARQL binding category.

    Args:
        datatype: ``sh:datatype`` value, or ``None``.
        is_iri: True when the property values are IRIs (class, nodeKind, or sh:in).

    Returns:
        Category string consumed by the SPARQL builder and GeoJSON translator.
    """
    if is_iri:
        return "iri_with_label"
    if datatype is not None and str(datatype) == str(XSD.anyURI):
        return "uri_literal"
    if datatype is not None and str(datatype) == str(XSD.boolean):
        return "boolean"
    if datatype is not None and str(datatype) in (str(XSD.string), str(RDF.langString)):
        return "lang_literal"
    return "simple_literal"

_infer_filter_type(path, category, datatype)

Choose the filter widget for a property, or none if display-only.

Parameters:

Name	Type	Description	Default
path	Node	Property path URIRef.	required
category	str	Inferred PropertyCategory.	required
datatype	Node | None	sh:datatype value, or None.	required

Returns:

Type	Description
FilterType	Filter widget type used by the panel, or none.

Source code in src/backend/app/shacl_to_entities.py

def _infer_filter_type(path: Node, category: str, datatype: Node | None) -> FilterType:
    """Choose the filter widget for a property, or ``none`` if display-only.

    Args:
        path: Property path URIRef.
        category: Inferred ``PropertyCategory``.
        datatype: ``sh:datatype`` value, or ``None``.

    Returns:
        Filter widget type used by the panel, or ``none``.
    """
    if path in DISPLAY_ONLY or category == "uri_literal":
        return "none"
    if category in _FILTER_BY_CATEGORY:
        return _FILTER_BY_CATEGORY[category]
    by_datatype = _FILTER_BY_DATATYPE.get(str(datatype) if datatype is not None else "")
    if by_datatype:
        return by_datatype
    return "multiselect" if category == "lang_literal" else "none"