feat(processing): add module to process inlining

Silvanoc · Silvanoc · commit a9453e10980e · 2025-07-17T18:14:01.000+02:00
Trying to address issue 2813 [1] inconsistencies have been identified WRT how object inlining is behaving depending on the values of `inlined`, `inlined_as_list` and the presence/absence of an identifier in the range class. These inconsistencies appear from the fact that no normalization is happening on schema loading (not only in SchemaLoader, but also in SchemaView) and some consumers apply their own logic. This patch provides a module that should be used on any schema loading (as of now SchemaLoader and SchemaView) to have a common behavior. The code is structured in a way that it covers all potential combinations in an easy to understand manner. Unit testing is also provided for the module. [1]: linkml/linkml#2813 Signed-off-by: Silvano Cirujano Cuesta <silvano.cirujano-cuesta@siemens.com>
diff --git a/linkml_runtime/processing/inlining.py b/linkml_runtime/processing/inlining.py
@@ -0,0 +1,122 @@
+from logging import Logger
+from typing import cast
+
+from linkml_runtime.linkml_model.meta import (
+    ClassDefinitionName,
+    SchemaDefinition,
+    SlotDefinition,
+)
+
+
+def _create_function_dispatcher(slot: SlotDefinition, logger: Logger) -> None:
+    """Function dispatcher for slot inlining processing"""
+
+    def set_inlined_and_report(range_class_has_identifier: bool) -> None:
+        slot.inlined = True
+        text_identifier = "with an identifier" if range_class_has_identifier else "without an identifier"
+        msg = (
+            f"Slot '{slot.name}' is requesting for an object {text_identifier} inlining as a "
+            + "list, but no inlining requested! Forcing `inlined: true`!!"
+        )
+        logger.warning(msg)
+
+    def debug_output(range_class_has_identifier: bool) -> None:
+        msg = (
+            f"Slot '{slot.name}' has a complete inlining specification: "
+            + f"range class has identifier: {range_class_has_identifier},"
+        )
+        if slot.inlined_as_list is None:
+            msg += f"`inlined: {slot.inlined}`, `inlined_as_list` unspecified."
+        else:
+            msg += f"`inlined: {slot.inlined}` and `inlined_as_list: {slot.inlined_as_list}`"
+        logger.debug(msg)
+
+    def warning(range_class_has_identifier: bool) -> None:
+        text_identifier = "with an identifier" if range_class_has_identifier else "without an identifier"
+        msg = (
+            f"Slot '{slot.name}' has following illogic or incomplete inlining "
+            + f"specification: `inlined: {slot.inlined}` and `inlined_as_list: "
+            + f"{slot.inlined_as_list}` for objects {text_identifier}"
+        )
+        logger.warning(msg)
+
+    function_map = {
+        # OK
+        (True, True, True): debug_output,
+        # OK
+        (True, True, False): debug_output,
+        # what type of inlining to use?
+        (True, True, None): warning,
+        # overriding specified value!!
+        (True, False, True): set_inlined_and_report,
+        # why specifying inlining type if no inlining?
+        (True, False, False): warning,
+        # OK
+        (True, False, None): debug_output,
+        # applying implicit default!!
+        (True, None, True): set_inlined_and_report,
+        # why specifying inlining type if inlining not requested?
+        (True, None, False): warning,
+        # no defaults, in-code implicit defaults will apply
+        (True, None, None): warning,
+        # OK
+        (False, True, True): debug_output,
+        # how to select a key for an object without an identifier?
+        (False, True, False): warning,
+        # no defaults, in-code implicit defaults will apply
+        (False, True, None): warning,
+        # how to add a reference to an object without an identifier?
+        (False, False, True): warning,
+        # how to add a reference to an object without an identifier?
+        (False, False, False): warning,
+        # how to add a reference to an object without an identifier?
+        (False, False, None): warning,
+        # applying implicit default!!
+        (False, None, True): set_inlined_and_report,
+        # why specifying inlining type if inlining not requested?
+        (False, None, False): warning,
+        # no defaults, in-code implicit defaults will apply
+        (False, None, None): warning,
+    }
+
+    def dispatch(range_class_has_identifier, inlined, inlined_as_list):
+        # func = function_map.get((range_class_has_identifier, inlined, inlined_as_list), default_function)
+        func = function_map.get((range_class_has_identifier, inlined, inlined_as_list))
+        return func(range_class_has_identifier)
+
+    return dispatch
+
+
+def process(slot: SlotDefinition, schema: SchemaDefinition, logger: Logger) -> None:
+    """
+    Processing the inlining behavior of a slot, including the type of inlining
+    (as a list or as a dictionary).
+
+    Processing encompasses analyzing the combination of elements relevant for
+    object inlining (reporting the result of the analysis with different logging
+    levels) and enforcing certain values.
+
+    It is important to take into account following:
+    - slot.inlined and slot.inlined_as_list can have three different values:
+    True, False or None (if nothing specified in the schema)
+    - if a class has an identifier is a pure boolean
+
+    Changes to `inlined` are applied directly on the provided slot object.
+
+    :param slot: the slot to process
+    :param schema: the schema in which the slot is contained
+    :param logger: the logger to use
+    """
+
+    # first of all, validate that the values of `inlined` and `inlined_as_list` are legal
+    # either `True` or `False` (if specified) or `None` (if nothing specified)
+    for value in ("inlined", "inlined_as_list"):
+        if getattr(slot, value) not in (True, False, None):
+            raise ValueError(
+                f"Invalid value for '{value}' in the schema for slot " + f"'{slot.name}': '{getattr(slot, value)}'"
+            )
+    range_class = schema.classes[cast(ClassDefinitionName, slot.range)]
+    range_has_identifier = any([schema.slots[s].identifier or schema.slots[s].key for s in range_class.slots])
+
+    dispatcher = _create_function_dispatcher(slot, logger)
+    dispatcher(range_has_identifier, slot.inlined, slot.inlined_as_list)
diff --git a/tests/test_processing/test_inlining_processor.py b/tests/test_processing/test_inlining_processor.py
@@ -0,0 +1,115 @@
+import logging
+
+import pytest
+
+from linkml_runtime.linkml_model.meta import (
+    ClassDefinition,
+    SlotDefinition,
+)
+from linkml_runtime.processing import inlining
+from linkml_runtime.utils.schema_builder import SchemaBuilder
+
+
+def prepare_schema(with_identifier, inlined, inlined_as_list):
+    builder = SchemaBuilder()
+
+    id = SlotDefinition(name="id", identifier=True)
+    builder.add_slot(id)
+
+    range_class = ClassDefinition(name="RangeClass")
+    if with_identifier:
+        range_class.slots = ["id"]
+    builder.add_class(range_class)
+
+    slot = SlotDefinition(name="slot_under_test", range=range_class.name)
+    if isinstance(inlined, bool):
+        slot.inlined = inlined
+    if isinstance(inlined_as_list, bool):
+        slot.inlined_as_list = inlined_as_list
+    builder.add_slot(slot)
+
+    return (slot, builder.schema)
+
+
+@pytest.mark.parametrize(
+    ("with_identifier", "inlined", "inlined_as_list"),
+    [
+        (True, True, True),
+        (True, True, False),
+        (True, False, None),
+        (False, True, True),
+    ],
+)
+def test_report_ok(with_identifier, inlined, inlined_as_list, caplog):
+    """Test that combinations that are clear an unproblematic only generate debug output."""
+    logger = logging.getLogger("Test")
+    caplog.set_level(logging.DEBUG)
+
+    slot, schema = prepare_schema(with_identifier, inlined, inlined_as_list)
+    inlining.process(slot, schema, logger)
+    for logrecord in caplog.records:
+        assert logrecord.levelname == "DEBUG"
+        assert " complete inlining specification" in logrecord.message
+
+
+@pytest.mark.parametrize(
+    ("with_identifier", "inlined", "inlined_as_list"),
+    [
+        # overriding specified `inlined: false` with `inlined: true`!!
+        (True, False, True),
+        # applying implicit default!!
+        (True, None, True),
+        # applying implicit default!!
+        (False, None, True),
+    ],
+)
+def test_force_inlined(with_identifier, inlined, inlined_as_list, caplog):
+    """Test that combinations that end up forcing `inlined: true` does so and generate a warning."""
+    logger = logging.getLogger("Test")
+    caplog.set_level(logging.WARNING)
+
+    slot, schema = prepare_schema(with_identifier, inlined, inlined_as_list)
+    inlining.process(slot, schema, logger)
+    assert slot.inlined
+    for logrecord in caplog.records:
+        assert logrecord.levelname == "WARNING"
+        assert "Forcing `inlined: true`!!" in logrecord.message
+
+
+@pytest.mark.parametrize(
+    ("with_identifier", "inlined", "inlined_as_list"),
+    [
+        # what type of inlining to use?
+        (True, True, None),
+        # why specifying inlining type if no inlining?
+        (True, False, False),
+        # why specifying inlining type if inlining not requested?
+        (True, None, False),
+        # no defaults, in-code implicit defaults will apply
+        (True, None, None),
+        # how to select a key for an object without an identifier?
+        (False, True, False),
+        # no defaults, in-code implicit defaults will apply
+        (False, True, None),
+        # how to add a reference to an object without an identifier?
+        (False, False, True),
+        # how to add a reference to an object without an identifier?
+        (False, False, False),
+        # how to add a reference to an object without an identifier?
+        (False, False, None),
+        # why specifying inlining type if inlining not requested?
+        (False, None, False),
+        # no defaults, in-code implicit defaults will apply
+        (False, None, None),
+    ],
+)
+def test_warn_inconsistencies(with_identifier, inlined, inlined_as_list, caplog):
+    """Test that combinations that are somehow illogical or incomplete are flagged raising a warning."""
+    logger = logging.getLogger("Test")
+    caplog.set_level(logging.WARNING)
+
+    slot, schema = prepare_schema(with_identifier, inlined, inlined_as_list)
+    inlining.process(slot, schema, logger)
+    for logrecord in caplog.records:
+        assert logrecord.levelname == "WARNING"
+        assert "illogic or incomplete inlining specification" in logrecord.message
