feat(generators): add --normalize-prefixes flag for well-known prefix names

Add an opt-in --normalize-prefixes flag to OWL, SHACL, and JSON-LD
Context generators that normalises non-standard prefix aliases to
well-known names from a static prefix map (derived from rdflib 7.x
defaults, cross-checked against prefix.cc consensus).

Key design decisions:
- Static frozen map (MappingProxyType) instead of runtime
  Graph().namespaces() lookup eliminates rdflib version dependency
  (defaults changed between 6.x/7.x)
- Both http://schema.org/ and https://schema.org/ map to 'schema'
  (linkml-runtime uses HTTP, W3C prefers HTTPS); likewise for wgs84
- Shared normalize_graph_prefixes() helper used by OWL and SHACL
  generators — same explicit remap approach as JSON-LD context generator
  (replaces blunt override=False which dragged in all 29 rdflib defaults)
- Two-phase graph normalisation: Phase 1 normalises schema-declared
  prefixes, Phase 2 cleans up runtime-injected bindings (e.g. metamodel
  defaults that cause orphaned prefixes like 'schema1')
- Collision detection: when the standard prefix name is already
  user-declared for a different namespace, normalisation is skipped
  with a warning to prevent silent data loss
- Context generator handles three cases: unbound standard prefix,
  stale binding (different URI), and duplicate binding (same URI)

When enabled:
- OWL/SHACL generators bind schema prefixes normally, then post-process
  via normalize_graph_prefixes() to rebind non-standard aliases
- ContextGenerator remaps non-standard prefix names to their standard
  equivalents and applies the remap consistently to CURIE generation

The flag defaults to off, preserving existing behaviour.

Tests cover OWL, SHACL, and context generators with sdo->schema,
dce->dc, http/https edge case, custom prefix preservation, flag-off
backward compatibility, cross-generator consistency, prefix collision
detection, schema1 regression prevention, and static map integrity.

Signed-off-by: jdsika <carlo.van-driesten@bmw.de>
Signed-off-by: jdsika <carlo.van-driesten@vdl.digital>

Author: jdsika

packages/linkml/src/linkml/generators/jsonldcontextgen.py

@@ -15,7 +15,7 @@
 
 from linkml._version import __version__
 from linkml.utils.deprecation import deprecated_fields
-from linkml.utils.generator import Generator, shared_arguments
+from linkml.utils.generator import Generator, shared_arguments, well_known_prefix_map
 from linkml_runtime.linkml_model.meta import ClassDefinition, SlotDefinition
 from linkml_runtime.linkml_model.types import SHEX
 from linkml_runtime.utils.formatutils import camelcase, underscore
@@ -66,6 +66,9 @@ class ContextGenerator(Generator):
     frame_root: str | None = None
 
     def __post_init__(self) -> None:
+        # Must be set before super().__post_init__() because the parent triggers
+        # the visitor pattern (visit_schema), which accesses _prefix_remap.
+        self._prefix_remap: dict[str, str] = {}
         super().__post_init__()
         if self.namespaces is None:
             raise TypeError("Schema text must be supplied to context generator.  Preparsed schema will not work")
@@ -80,6 +83,10 @@ def __post_init__(self) -> None:
             self._local_classes = set(sv.all_classes(imports=False).keys())
             self._local_slots = set(sv.all_slots(imports=False).keys())
 
+    def add_prefix(self, ncname: str) -> None:
+        """Add a prefix, applying well-known prefix normalisation when enabled."""
+        super().add_prefix(self._prefix_remap.get(ncname, ncname))
+
     def visit_schema(self, base: str | Namespace | None = None, output: str | None = None, **_):
         # Add any explicitly declared prefixes
         for prefix in self.schema.prefixes.values():
@@ -89,6 +96,68 @@ def visit_schema(self, base: str | Namespace | None = None, output: str | None =
         for pfx in self.schema.emit_prefixes:
             self.add_prefix(pfx)
 
+        # Normalise well-known prefix names when --normalize-prefixes is set.
+        # If the schema declares a non-standard alias for a namespace that has
+        # a well-known standard name (e.g. ``sdo`` for
+        # ``https://schema.org/``), replace the alias with the standard name
+        # so that generated JSON-LD contexts use the conventional prefix.
+        #
+        # Three cases are handled:
+        # 1. Standard prefix is not yet bound → just rebind from old to new.
+        # 2. Standard prefix is bound to a *different* URI:
+        #    a. User-declared (in schema.prefixes) → collision, skip with warning.
+        #    b. Runtime default (e.g. linkml-runtime's ``schema: http://…``)
+        #       → remove stale binding, then rebind.
+        # 3. Standard prefix is already bound to the *same* URI (duplicate)
+        #    → just drop the non-standard alias.
+        #
+        # A remap dict is stored for ``_build_element_id`` because
+        # ``prefix_suffix()`` splits CURIEs on ``:`` without looking up the
+        # namespace dict.
+        self._prefix_remap.clear()
+        if self.normalize_prefixes:
+            wk = well_known_prefix_map()
+            for old_pfx in list(self.namespaces):
+                url = str(self.namespaces[old_pfx])
+                std_pfx = wk.get(url)
+                if not std_pfx or std_pfx == old_pfx:
+                    continue
+                if std_pfx in self.namespaces:
+                    if str(self.namespaces[std_pfx]) != url:
+                        # Case 2: std_pfx is bound to a different URI.
+                        # If the user explicitly declared std_pfx in the schema,
+                        # it is intentional — skip to avoid data loss.
+                        if std_pfx in self.schema.prefixes:
+                            self.logger.warning(
+                                "Prefix collision: cannot rename '%s' to '%s' because '%s' is "
+                                "already declared for <%s>; skipping normalisation for <%s>",
+                                old_pfx,
+                                std_pfx,
+                                std_pfx,
+                                str(self.namespaces[std_pfx]),
+                                url,
+                            )
+                            continue
+                        # Not user-declared (e.g. linkml-runtime default) — safe to remove
+                        self.emit_prefixes.discard(std_pfx)
+                        del self.namespaces[std_pfx]
+                    else:
+                        # Case 3: standard prefix already bound to same URI
+                        # — just drop the non-standard alias
+                        del self.namespaces[old_pfx]
+                        if old_pfx in self.emit_prefixes:
+                            self.emit_prefixes.discard(old_pfx)
+                            self.emit_prefixes.add(std_pfx)
+                        self._prefix_remap[old_pfx] = std_pfx
+                        continue
+                # Case 1 (or Case 2 after stale removal): bind standard name
+                self.namespaces[std_pfx] = self.namespaces[old_pfx]
+                del self.namespaces[old_pfx]
+                if old_pfx in self.emit_prefixes:
+                    self.emit_prefixes.discard(old_pfx)
+                    self.emit_prefixes.add(std_pfx)
+                self._prefix_remap[old_pfx] = std_pfx
+
         # Add the default prefix
         if self.schema.default_prefix:
             dflt = self.namespaces.prefix_for(self.schema.default_prefix)
@@ -310,6 +379,11 @@ def _build_element_id(self, definition: Any, uri: str) -> None:
         @return: None
         """
         uri_prefix, uri_suffix = self.namespaces.prefix_suffix(uri)
+        # Apply well-known prefix normalisation (e.g. sdo → schema).
+        # prefix_suffix() splits CURIEs on ':' without checking the
+        # namespace dict, so it may return a stale alias.
+        if uri_prefix and uri_prefix in self._prefix_remap:
+            uri_prefix = self._prefix_remap[uri_prefix]
         is_default_namespace = uri_prefix == self.context_body["@vocab"] or uri_prefix == self.namespaces.prefix_for(
             self.context_body["@vocab"]
         )

packages/linkml/src/linkml/generators/owlgen.py

@@ -20,7 +20,7 @@
 from linkml import METAMODEL_NAMESPACE_NAME
 from linkml._version import __version__
 from linkml.utils.deprecation import deprecation_warning
-from linkml.utils.generator import Generator, shared_arguments
+from linkml.utils.generator import Generator, normalize_graph_prefixes, shared_arguments
 from linkml_runtime import SchemaView
 from linkml_runtime.linkml_model.meta import (
     AnonymousClassExpression,
@@ -233,6 +233,10 @@ def as_graph(self) -> Graph:
             self.graph.bind(prefix, self.metamodel.namespaces[prefix])
         for pfx in schema.prefixes.values():
             self.graph.namespace_manager.bind(pfx.prefix_prefix, URIRef(pfx.prefix_reference))
+        if self.normalize_prefixes:
+            normalize_graph_prefixes(
+                graph, {str(v.prefix_prefix): str(v.prefix_reference) for v in schema.prefixes.values()}
+            )
         graph.add((base, RDF.type, OWL.Ontology))
 
         # Add main schema elements

packages/linkml/src/linkml/generators/shaclgen.py

@@ -13,7 +13,7 @@
 from linkml.generators.common.subproperty import get_subproperty_values, is_uri_range
 from linkml.generators.shacl.shacl_data_type import ShaclDataType
 from linkml.generators.shacl.shacl_ifabsent_processor import ShaclIfAbsentProcessor
-from linkml.utils.generator import Generator, shared_arguments
+from linkml.utils.generator import Generator, normalize_graph_prefixes, shared_arguments
 from linkml_runtime.linkml_model.meta import ClassDefinition, ElementName
 from linkml_runtime.utils.formatutils import underscore
 from linkml_runtime.utils.yamlutils import TypedNode, extended_float, extended_int, extended_str
@@ -105,6 +105,10 @@ def as_graph(self) -> Graph:
 
         for pfx in self.schema.prefixes.values():
             g.bind(str(pfx.prefix_prefix), pfx.prefix_reference)
+        if self.normalize_prefixes:
+            normalize_graph_prefixes(
+                g, {str(v.prefix_prefix): str(v.prefix_reference) for v in self.schema.prefixes.values()}
+            )
 
         for c in sv.all_classes(imports=not self.exclude_imports).values():
 

packages/linkml/src/linkml/utils/generator.py

@@ -20,11 +20,12 @@
 import os
 import re
 import sys
+import types
 from collections.abc import Callable, Mapping
 from dataclasses import dataclass, field
 from functools import lru_cache
 from pathlib import Path
-from typing import ClassVar, TextIO, Union, cast
+from typing import TYPE_CHECKING, ClassVar, TextIO, Union, cast
 
 import click
 from click import Argument, Command, Option
@@ -58,6 +59,9 @@
 from linkml_runtime.utils.formatutils import camelcase, underscore
 from linkml_runtime.utils.namespaces import Namespaces
 
+if TYPE_CHECKING:
+    from rdflib import Graph
+
 logger = logging.getLogger(__name__)
 
 
@@ -78,6 +82,127 @@ def _resolved_metamodel(mergeimports):
     return metamodel
 
 
+def well_known_prefix_map() -> dict[str, str]:
+    """Return a mapping from namespace URI to standard prefix name.
+
+    Uses a frozen, version-independent map derived from rdflib 7.x curated
+    defaults (which align with the `prefix.cc <https://prefix.cc>`_ community
+    consensus registry).  The map is **not** computed at runtime from
+    ``Graph().namespaces()`` because those defaults can change across rdflib
+    releases (they differ between 6.x and 7.x), which would silently alter
+    generator output.
+
+    This allows generators to normalise non-standard prefix aliases
+    (e.g. ``sdo`` for ``https://schema.org/``) to their conventional names.
+
+    Both ``http`` and ``https`` variants of schema.org are included because
+    the linkml-runtime historically binds ``schema: http://schema.org/``
+    while rdflib (and the W3C) prefer ``https://schema.org/``.
+    """
+    return dict(_WELL_KNOWN_PREFIX_MAP)
+
+
+# Frozen, version-independent map: namespace URI → canonical prefix name.
+# Source: rdflib 7.x defaults, cross-checked against https://prefix.cc
+_WELL_KNOWN_PREFIX_MAP: types.MappingProxyType[str, str] = types.MappingProxyType(
+    {
+        "https://brickschema.org/schema/Brick#": "brick",
+        "http://www.w3.org/ns/csvw#": "csvw",
+        "http://purl.org/dc/elements/1.1/": "dc",
+        "http://purl.org/dc/dcam/": "dcam",
+        "http://www.w3.org/ns/dcat#": "dcat",
+        "http://purl.org/dc/dcmitype/": "dcmitype",
+        "http://purl.org/dc/terms/": "dcterms",
+        "http://usefulinc.com/ns/doap#": "doap",
+        "http://xmlns.com/foaf/0.1/": "foaf",
+        "http://www.opengis.net/ont/geosparql#": "geo",
+        "http://www.w3.org/ns/odrl/2/": "odrl",
+        "http://www.w3.org/ns/org#": "org",
+        "http://www.w3.org/2002/07/owl#": "owl",
+        "http://www.w3.org/ns/dx/prof/": "prof",
+        "http://www.w3.org/ns/prov#": "prov",
+        "http://purl.org/linked-data/cube#": "qb",
+        "http://www.w3.org/1999/02/22-rdf-syntax-ns#": "rdf",
+        "http://www.w3.org/2000/01/rdf-schema#": "rdfs",
+        "https://schema.org/": "schema",
+        "http://schema.org/": "schema",  # HTTP variant (linkml-runtime uses this)
+        "http://www.w3.org/ns/shacl#": "sh",
+        "http://www.w3.org/2004/02/skos/core#": "skos",
+        "http://www.w3.org/ns/sosa/": "sosa",
+        "http://www.w3.org/ns/ssn/": "ssn",
+        "http://www.w3.org/2006/time#": "time",
+        "http://purl.org/vocab/vann/": "vann",
+        "http://rdfs.org/ns/void#": "void",
+        "https://www.w3.org/2003/01/geo/wgs84_pos#": "wgs",
+        "http://www.w3.org/2003/01/geo/wgs84_pos#": "wgs",  # HTTP variant (W3C canonical)
+        "http://www.w3.org/XML/1998/namespace": "xml",
+        "http://www.w3.org/2001/XMLSchema#": "xsd",
+    }
+)
+
+
+def normalize_graph_prefixes(graph: "Graph", schema_prefixes: dict[str, str]) -> None:
+    """Normalise non-standard prefix aliases in an rdflib Graph.
+
+    For each prefix bound in *schema_prefixes* (mapping prefix name →
+    namespace URI), check whether ``well_known_prefix_map()`` knows a
+    standard name for that URI.  If the standard name differs from the
+    schema-declared name, rebind the namespace to the standard name.
+
+    This is the **shared implementation** used by OWL, SHACL, and (via a
+    different code-path) JSON-LD context generators so that all serialisation
+    formats agree on prefix names when ``--normalize-prefixes`` is active.
+
+    :param graph: rdflib Graph whose namespace bindings should be adjusted.
+    :param schema_prefixes: mapping of prefix name → namespace URI string,
+        typically from ``schema.prefixes``.
+    """
+    from rdflib import Namespace
+
+    wk = well_known_prefix_map()
+
+    # Phase 1: normalise schema-declared prefixes.
+    for old_pfx, ns_uri in schema_prefixes.items():
+        ns_str = str(ns_uri)
+        std_pfx = wk.get(ns_str)
+        if not std_pfx or std_pfx == old_pfx:
+            continue
+        # Collision: the user explicitly declared std_pfx for a different
+        # namespace — do not clobber their binding.
+        if std_pfx in schema_prefixes and schema_prefixes[std_pfx] != ns_str:
+            logger.warning(
+                "Prefix collision: cannot rename '%s' to '%s' because '%s' is already "
+                "declared for <%s>; skipping normalisation for <%s>",
+                old_pfx,
+                std_pfx,
+                std_pfx,
+                schema_prefixes[std_pfx],
+                ns_str,
+            )
+            continue
+        # Rebind: remove old prefix, add standard prefix.
+        # ``replace=True`` forces the new prefix even if the prefix name
+        # is already bound to a different namespace.
+        graph.bind(std_pfx, Namespace(ns_str), override=True, replace=True)
+
+    # Phase 2: normalise runtime-injected bindings (e.g. metamodel defaults).
+    # The linkml-runtime / rdflib may inject well-known namespaces under
+    # non-standard prefix names.  After Phase 1 rebinds schema-declared
+    # prefixes, orphaned runtime bindings can appear as ``schema1``, ``dc0``,
+    # etc.  Scan the graph's current bindings and fix any that map to a
+    # well-known namespace under a non-standard name, provided the standard
+    # name isn't already claimed by the user for a different namespace.
+    for pfx, ns in list(graph.namespaces()):
+        pfx_str, ns_str = str(pfx), str(ns)
+        std_pfx = wk.get(ns_str)
+        if not std_pfx or std_pfx == pfx_str:
+            continue
+        # Same collision check as Phase 1: respect user-declared prefixes.
+        if std_pfx in schema_prefixes and schema_prefixes[std_pfx] != ns_str:
+            continue
+        graph.bind(std_pfx, Namespace(ns_str), override=True, replace=True)
+
+
 @dataclass
 class Generator(metaclass=abc.ABCMeta):
     """
@@ -180,6 +305,12 @@ class Generator(metaclass=abc.ABCMeta):
     stacktrace: bool = False
     """True means print stack trace, false just error message"""
 
+    normalize_prefixes: bool = False
+    """True means normalise non-standard prefix aliases to well-known names
+    from the static ``_WELL_KNOWN_PREFIX_MAP`` (derived from rdflib 7.x
+    defaults / prefix.cc consensus).  E.g. ``sdo`` → ``schema`` for
+    ``https://schema.org/``."""
+
     include: str | Path | SchemaDefinition | None = None
     """If set, include extra schema outside of the imports mechanism"""
 
@@ -986,6 +1117,16 @@ def decorator(f: Command) -> Command:
                 callback=stacktrace_callback,
             )
         )
+        f.params.append(
+            Option(
+                ("--normalize-prefixes/--no-normalize-prefixes",),
+                default=False,
+                show_default=True,
+                help="Normalise non-standard prefix aliases to rdflib's curated default names "
+                "(e.g. sdo → schema for https://schema.org/). "
+                "Supported by OWL, SHACL, and JSON-LD Context generators.",
+            )
+        )
 
         return f