Skip to content

Labels

Find duplicate names or descriptions

find_duplicate_labels() finds nodes with more than one distinct annotation literal. It accepts a Path, an RDF string, or an RDFLib Graph. Paths can identify an RDF file or a directory of RDF files.

By default, it checks names using schema:name (https://schema.org/name), rdfs:label, dcterms:title, and skos:prefLabel. Set names_or_descriptions="descriptions" to check schema:description (https://schema.org/description), rdfs:comment, dcterms:description, and skos:definition instead.

The result is a dictionary mapping each affected node to a set of its distinct literals across the selected predicates. Nodes can be IRIs or blank nodes, including resources used as predicates or objects elsewhere in the graph. Identical literals on different predicates count once. Differences in spelling, datatype, or language count separately, including a language-tagged literal versus one without a language tag. Comparisons use the literals as stored by RDFLib, which may normalize typed literals when loading RDF.

from pathlib import Path

from rdflib import URIRef

from kurra.labels import find_duplicate_labels

source = Path("vocabulary.ttl")

# Find multiple distinct names using the default predicates.
names = find_duplicate_labels(source)

# Find multiple distinct descriptions instead.
descriptions = find_duplicate_labels(source, names_or_descriptions="descriptions")

# Extend the name predicates with additional annotation IRIs.
extra_names = find_duplicate_labels(
    source,
    additional_annotation_predicates=[
        URIRef("https://example.com/displayName"),
        URIRef("https://example.com/shortName"),
    ],
)

# Additional predicates can also extend the description predicates.
extra_descriptions = find_duplicate_labels(
    source,
    names_or_descriptions="descriptions",
    additional_annotation_predicates=[URIRef("https://example.com/description")],
)

for node, values in names.items():
    print(node.n3(), sorted(value.n3() for value in values))

Additional predicates supplement the defaults; they do not replace them. With no duplicates, the function returns an empty dictionary. Values other than "names" or "descriptions" raise ValueError.

API reference

kurra.labels

Functions to find RDF elements missing labels, and to acquire them from KurrawongAI's Semantic Background or another provided context.

find_duplicate_labels

find_duplicate_labels(p: Path | str | Graph, names_or_descriptions: Literal['names', 'descriptions'] = 'names', additional_annotation_predicates: list[URIRef] | None = None) -> dict[IdentifiedNode, set[RDFLiteral]]

Find nodes with more than one distinct name or description literal.

Parameters:

Name Type Description Default
p Path | str | Graph

An RDF file path, directory, RDF string, or Graph to scan.

required
names_or_descriptions Literal['names', 'descriptions']

Use name predicates by default, or description predicates.

'names'
additional_annotation_predicates list[URIRef] | None

Extra annotation predicate IRIs to search. Defaults to no additional predicates.

None

Returns:

Type Description
dict[IdentifiedNode, set[Literal]]

A dict mapping each affected node to its distinct literals across the selected

dict[IdentifiedNode, set[Literal]]

predicates. Literal spelling, datatype, and language distinguish values as

dict[IdentifiedNode, set[Literal]]

stored in the graph. Identical values on different predicates count once.

Raises:

Type Description
ValueError

If names_or_descriptions is neither "names" nor "descriptions".

Source code in kurra/labels.py
def find_duplicate_labels(
    p: Path | str | Graph,
    names_or_descriptions: Literal["names", "descriptions"] = "names",
    additional_annotation_predicates: list[URIRef] | None = None,
) -> dict[IdentifiedNode, set[RDFLiteral]]:
    """Find nodes with more than one distinct name or description literal.

    Args:
        p: An RDF file path, directory, RDF string, or Graph to scan.
        names_or_descriptions: Use name predicates by default, or description predicates.
        additional_annotation_predicates: Extra annotation predicate IRIs to search.
            Defaults to no additional predicates.

    Returns:
        A dict mapping each affected node to its distinct literals across the selected
        predicates. Literal spelling, datatype, and language distinguish values as
        stored in the graph. Identical values on different predicates count once.

    Raises:
        ValueError: If names_or_descriptions is neither "names" nor "descriptions".
    """
    if names_or_descriptions not in ("names", "descriptions"):
        raise ValueError('names_or_descriptions must be "names" or "descriptions"')

    predicates = set(
        LABEL_PREDICATES if names_or_descriptions == "names" else DESCRIPTION_PREDICATES
    )
    predicates.update(additional_annotation_predicates or [])
    graph = load_graph(p)
    labels: dict[IdentifiedNode, set[RDFLiteral]] = {}
    for predicate in predicates:
        for subject, value in graph.subject_objects(predicate):
            if isinstance(subject, IdentifiedNode) and isinstance(value, RDFLiteral):
                labels.setdefault(subject, set()).add(value)

    return {node: values for node, values in labels.items() if len(values) > 1}

find_missing_labels

find_missing_labels(p: Path | str | Graph, local_context: Path | Graph | None = None) -> Iterable[URIRef]

Find all the IRIs in a graph missing labels.

Parameters:

Name Type Description Default
p Path | str | Graph

The RDF source to scan for IRIs missing labels as a file path, directory, RDF string, or Graph.

required
local_context Path | Graph | None

An RDF file, directory, or Graph containing labels to check against, in addition to p itself.

None

Returns:

Type Description
Iterable[URIRef]

The IRIs missing a label.

Source code in kurra/labels.py
def find_missing_labels(
    p: Path | str | Graph, local_context: Path | Graph | None = None
) -> Iterable[URIRef]:
    """Find all the IRIs in a graph missing labels.

    Args:
        p: The RDF source to scan for IRIs missing labels as a file path, directory, RDF string, or Graph.
        local_context: An RDF file, directory, or Graph containing labels to check against, in addition to `p` itself.

    Returns:
        The IRIs missing a label.
    """

    # find all the things missing labels
    missing_labels = set()

    g = load_graph(p)

    for s in iter_iris(g):
        for node in LABEL_PREDICATES:
            if g.value(subject=s, predicate=node):
                break
        else:
            missing_labels.add(s)

    if local_context is not None:
        tx: set[URIRef] = set()

        c = load_graph(local_context)
        for t in missing_labels:
            has_context_label = any(
                c.value(subject=t, predicate=pred) for pred in LABEL_PREDICATES
            )
            if not has_context_label:
                tx.add(t)
        return tx
    else:
        return sorted(missing_labels)

get_labels

get_labels(iris: list[URIRef], context: Graph | str | Path = 'https://fuseki.dev.kurrawong.ai/semback/sparql', return_type: Literal['graph'] = 'graph', http_client: Client | None = None) -> Graph
get_labels(iris: list[URIRef], context: Graph | str | Path, return_type: Literal['dict'], http_client: Client | None = None) -> dict[URIRef, str]
get_labels(iris: list[URIRef], context: Graph | str | Path = 'https://fuseki.dev.kurrawong.ai/semback/sparql', return_type: Literal['graph', 'dict'] = 'graph', http_client: Client | None = None) -> Graph | dict[URIRef, str]

Get labels for the given IRIs from a given context, by default the KurrawongAI Semantic Background.

Parameters:

Name Type Description Default
iris list[URIRef]

The IRIs to fetch labels for.

required
context Graph | str | Path

An RDF Graph, file, directory, or SPARQL endpoint containing labels to check against. Defaults to the KurrawongAI Semantic Background.

'https://fuseki.dev.kurrawong.ai/semback/sparql'
return_type Literal['graph', 'dict']

"graph" to return an RDF Graph of schema:name labels, or "dict" for a dict keyed by IRI.

'graph'
http_client Client | None

An optional HTTPX client to contain credentials if needed to access a SPARQL endpoint as context. A new one is created if not given.

None

Returns:

Type Description
Graph | dict[URIRef, str]

A Graph if return_type is "graph", or a dict of IRI to label if "dict".

Source code in kurra/labels.py
def get_labels(
    iris: list[URIRef],
    context: Graph | str | Path = "https://fuseki.dev.kurrawong.ai/semback/sparql",
    return_type: Literal["graph", "dict"] = "graph",
    http_client: httpx2.Client | None = None,
) -> Graph | dict[URIRef, str]:
    """Get labels for the given IRIs from a given context, by default the KurrawongAI Semantic Background.

    Args:
        iris: The IRIs to fetch labels for.
        context: An RDF Graph, file, directory, or SPARQL endpoint containing labels to check against. Defaults to the KurrawongAI Semantic Background.
        return_type: `"graph"` to return an RDF Graph of `schema:name` labels, or `"dict"` for a dict keyed by IRI.
        http_client: An optional HTTPX client to contain credentials if needed to access a SPARQL endpoint as context. A new one is created if not given.

    Returns:
        A Graph if `return_type` is `"graph"`, or a dict of IRI to label if `"dict"`.
    """
    iri_values_clause = build_values_clause({"iri": iris})
    predicate_values_clause = build_values_clause({"pred": LABEL_PREDICATES})

    where_clause = f"""
        WHERE {{
            ?iri ?pred ?label .
            {predicate_values_clause}
            {iri_values_clause}
        }}
        """

    if return_type == "graph":
        q = f"""
            PREFIX schema: <https://schema.org/>

            CONSTRUCT {{
                ?iri schema:name ?label
            }}
            {where_clause}
            """
        return query(context, q, http_client=http_client, return_format="python")
    else:
        q = f"""
            PREFIX schema: <https://schema.org/>

            SELECT ?iri ?label
            {where_clause}
            """
        d = {}
        for r in query(
            context,
            q,
            http_client=http_client,
            return_format="python",
            return_bindings_only=True,
        ):
            d[r["iri"]] = r["label"]
        return d

jsonld_context

jsonld_context(graph: Graph, vocabulary: Graph | None = None) -> dict[str, str]

Create a JSON-LD context mapping resource labels to their IRIs.

Parameters:

Name Type Description Default
graph Graph

The graph to generate a context for.

required
vocabulary Graph | None

An additional graph to source labels and class/property types from.

None

Returns:

Type Description
dict[str, str]

A dict mapping each generated JSON-LD term to its IRI.

Source code in kurra/labels.py
def jsonld_context(graph: Graph, vocabulary: Graph | None = None) -> dict[str, str]:
    """Create a JSON-LD context mapping resource labels to their IRIs.

    Args:
        graph: The graph to generate a context for.
        vocabulary: An additional graph to source labels and class/property types from.

    Returns:
        A dict mapping each generated JSON-LD term to its IRI.
    """
    result = {}
    all_iris = list(iter_iris(graph))
    if vocabulary is None:
        vocabulary = Graph()

    label_dict = cast(
        dict[str, str], get_labels(all_iris, vocabulary, return_type="dict")
    )
    for iri, label in label_dict.items():
        is_type = is_class(graph, URIRef(iri)) or is_class(vocabulary, URIRef(iri))

        # Create a label that is camelCase if it's a property and PascalCase if it's a class
        label_parts = [
            part.capitalize() if (i > 0 or is_type) else part
            for i, part in enumerate(SPLIT_REGEX.split(label))
        ]

        result["".join(label_parts)] = str(iri)

    return result