feat: expose the form attribute values are compared under

AttributeBinding.comparable returns the form filters compare a value under: NFC, and case folded unless the attribute is caseExact. A server or a database can keep this form to filter, sort and check uniqueness as ScimFilter.match does. SearchRequest.sort now uses it too, so it normalizes strings to NFC like filters do.

Author: azmeuk

doc/changelog.rst

@@ -9,6 +9,10 @@ Added
 - Filters accept a compared sub-attribute after a value selection, as Microsoft Entra ID sends
   it: ``emails[type eq "work"].value eq "x"`` reads as
   ``emails[type eq "work" and value eq "x"]``.
+- :meth:`AttributeBinding.comparable <scim2_models.AttributeBinding.comparable>` returns the form
+  a value is compared under: NFC, and case folded unless the attribute is ``caseExact``. A storage
+  can keep this form to filter, sort and check uniqueness as :meth:`~scim2_models.ScimFilter.match`
+  does.
 
 Changed
 ^^^^^^^
@@ -22,6 +26,11 @@ Changed
   from ``schemas``, such as ``schemas[value eq "urn:…:enterprise:2.0:User"]``, removes the extension.
   Before, the operation reported a change but the extension stayed.
 
+Fixed
+^^^^^
+- :meth:`SearchRequest.sort <scim2_models.SearchRequest.sort>` normalizes strings to NFC, as filters
+  do. A composed and a decomposed ``José`` now sort together.
+
 [0.10.6] - 2026-10-06
 ---------------------
 

scim2_models/messages/search_request.py

@@ -75,9 +75,7 @@ def _sort_value(resource: Any, binding: AttributeBinding | None) -> Any:
         value = getattr(value, binding.sub_field_name, None)
     # "String type attributes are case insensitive by default, unless the
     # attribute type is defined as a case-exact string", RFC7644 §3.4.2.3.
-    if isinstance(value, str) and not binding.case_exact:
-        return value.casefold()
-    return value
+    return binding.comparable(value)
 
 
 class SearchRequest(Message, ResponseParameters[ResourceT], Generic[ResourceT]):

scim2_models/path/resolution.py

@@ -6,6 +6,7 @@
 from typing import Any
 from typing import cast
 from typing import get_args
+from unicodedata import normalize
 
 from pydantic import TypeAdapter
 from pydantic import ValidationError
@@ -129,6 +130,33 @@ def get_annotation(self, annotation_type: type) -> Any:
             return None
         return model.get_field_annotation(self.target_field_name, annotation_type)
 
+    def comparable(self, value: Any) -> Any:
+        """Return the form a value of the attribute is compared under.
+
+        Filters, sorting and uniqueness checks compare values in this form, so
+        a storage that keeps it can compare as :meth:`~scim2_models.ScimFilter.match`
+        does. Strings are normalized to NFC, and case folded unless the attribute
+        is ``caseExact``. Other values are returned unchanged.
+
+        >>> from scim2_models import Path, User
+        >>> binding = Path[User]("userName").resolve()
+        >>> binding.comparable("BJensen")
+        'bjensen'
+
+        :param value: A value of the attribute.
+        :returns: The value in the form it is compared under.
+        """
+        if not isinstance(value, str):
+            return value
+
+        normalized = normalize("NFC", value)
+        if self.case_exact:
+            return normalized
+
+        # Case folding does not preserve the normalization form, so NFC is
+        # applied to its result too, and every operand comes out in the same form.
+        return normalize("NFC", normalized.casefold())
+
     def _nested_in(self, urn: str) -> "AttributeBinding":
         """Return the same attribute, qualified by the URN it was resolved under.
 

scim2_models/path/visitor.py

@@ -3,7 +3,6 @@
 from typing import Any
 from typing import Generic
 from typing import TypeVar
-from unicodedata import normalize
 
 from ..base import BaseModel
 from .expressions import AttrPath
@@ -102,29 +101,15 @@ def _is_present(value: Any) -> bool:
     return True
 
 
-def _comparable(value: Any, case_exact: bool) -> Any:
-    """Reduce a value to the form comparisons are performed on."""
-    if not isinstance(value, str):
-        return value
-
-    normalized = normalize("NFC", value)
-    if case_exact:
-        return normalized
-
-    # Case folding does not preserve the normalization form, so NFC is applied
-    # to its result too, and every operand comes out in the same form.
-    return normalize("NFC", normalized.casefold())
-
-
 def _compare(
-    actual: Any, expected: Any, op: CompareOperator, *, case_exact: bool = False
+    actual: Any, expected: Any, op: CompareOperator, resolved: AttributeBinding
 ) -> bool:
     """Apply a comparison operator to a single pair of values.
 
     Values of incomparable types never match, rather than raising, so that a
     filter over a heterogeneous collection stays usable. ``actual`` is read
     from the resource, ``expected`` is what the filter compares it against, and
-    ``case_exact`` says whether strings compare case-sensitively.
+    ``resolved`` is the attribute, which gives the form both are compared under.
     """
     if actual is None or expected is None:
         if op == CompareOperator.eq:
@@ -133,8 +118,8 @@ def _compare(
             return (actual is None) != (expected is None)
         return False
 
-    left = _comparable(actual, case_exact)
-    right = _comparable(expected, case_exact)
+    left = resolved.comparable(actual)
+    right = resolved.comparable(expected)
 
     if op in (CompareOperator.co, CompareOperator.sw, CompareOperator.ew):
         if not isinstance(left, str) or not isinstance(right, str):
@@ -230,21 +215,15 @@ def visit_comparison(self, node: Comparison) -> bool:
         actual = self._read(resolved)
 
         if not isinstance(actual, list):
-            return _compare(actual, expected, node.op, case_exact=resolved.case_exact)
+            return _compare(actual, expected, node.op, resolved)
 
         # A filter on a multi-valued attribute matches if any of its values
         # matches. The RFC does not say what that means for "ne", so the
         # universal reading is used: no value equals the operand.
         if node.op == CompareOperator.ne:
-            return all(
-                _compare(item, expected, node.op, case_exact=resolved.case_exact)
-                for item in actual
-            )
+            return all(_compare(item, expected, node.op, resolved) for item in actual)
 
-        return any(
-            _compare(item, expected, node.op, case_exact=resolved.case_exact)
-            for item in actual
-        )
+        return any(_compare(item, expected, node.op, resolved) for item in actual)
 
     def visit_present(self, node: Present) -> bool:
         resolved = self._resolve(node.attr_path)
@@ -300,7 +279,7 @@ def _matches_item(
                 type(item), item, strict=self.strict, urn_prefix=resolved.urn
             ).visit(val_filter)
 
-        return _ScalarEvaluator(item, case_exact=resolved.case_exact).visit(val_filter)
+        return _ScalarEvaluator(item, resolved).visit(val_filter)
 
 
 class _ScalarEvaluator(FilterVisitor[bool]):
@@ -313,17 +292,17 @@ class _ScalarEvaluator(FilterVisitor[bool]):
     attribute name cannot match.
     """
 
-    def __init__(self, value: Any, *, case_exact: bool = False):
+    def __init__(self, value: Any, resolved: AttributeBinding):
         self.value = value
-        self.case_exact = case_exact
+        self.resolved = resolved
 
     def _targets_self(self, node: Comparison | Present) -> bool:
         return node.attr_path.attr.lower() == "value" and not node.attr_path.sub_attr
 
     def visit_comparison(self, node: Comparison) -> bool:
         if not self._targets_self(node):
             return False
-        return _compare(self.value, node.value, node.op, case_exact=self.case_exact)
+        return _compare(self.value, node.value, node.op, self.resolved)
 
     def visit_present(self, node: Present) -> bool:
         return self._targets_self(node) and _is_present(self.value)

tests/test_filter_semantics.py

@@ -537,9 +537,11 @@ def test_comparison_matches_a_canonically_equivalent_operand():
 
 def test_a_case_exact_comparison_matches_a_canonically_equivalent_operand():
     """Case exactness constrains the casing, not the normalization form."""
-    assert _compare(COMPOSED, DECOMPOSED, CompareOperator.eq, case_exact=True)
-    assert not _compare(
-        COMPOSED.upper(), DECOMPOSED, CompareOperator.eq, case_exact=True
+    assert ScimFilter[User](f'externalId eq "{DECOMPOSED}"').match(
+        User(external_id=COMPOSED)
+    )
+    assert not ScimFilter[User](f'externalId eq "{DECOMPOSED}"').match(
+        User(external_id=COMPOSED.upper())
     )
 
 
@@ -947,7 +949,11 @@ def test_presence_of_a_value(value, expected):
 )
 def test_comparing_two_values(actual, expected_value, operator, expected):
     """Incomparable values never match rather than raising."""
-    assert _compare(actual, expected_value, CompareOperator(operator)) is expected
+    resolved = Path[User]("displayName").resolve()
+    assert (
+        _compare(actual, expected_value, CompareOperator(operator), resolved)
+        is expected
+    )
 
 
 def test_a_visitor_must_implement_every_node_type():

tests/test_path.py

@@ -1886,3 +1886,28 @@ def test_iter_paths_keeps_results_of_different_models_apart():
         in extended
     )
     assert not any(path.startswith("urn:") for path in plain)
+
+
+def test_comparable_folds_the_case_of_a_case_insensitive_string():
+    """A case-insensitive string is compared without its case."""
+    binding = Path[User]("userName").resolve()
+    assert binding.comparable("BJensen") == "bjensen"
+
+
+def test_comparable_keeps_the_case_of_a_case_exact_string():
+    """A case-exact string keeps its case."""
+    binding = Path[User]("externalId").resolve()
+    assert binding.comparable("BJensen") == "BJensen"
+
+
+@pytest.mark.parametrize("attribute", ["userName", "externalId"])
+def test_comparable_gives_composed_and_decomposed_strings_the_same_form(attribute):
+    """Strings are normalized to NFC, whatever their case sensitivity."""
+    binding = Path[User](attribute).resolve()
+    assert binding.comparable("Jos\u00e9") == binding.comparable("Jose\u0301")
+
+
+def test_comparable_leaves_other_values_unchanged():
+    """Only strings have a comparison form of their own."""
+    binding = Path[User]("active").resolve()
+    assert binding.comparable(True) is True

tests/test_search_request.py

@@ -731,6 +731,20 @@ def test_sort_ignores_the_case_of_a_case_insensitive_string():
     ]
 
 
+def test_sort_places_composed_and_decomposed_strings_together():
+    """Sorting compares strings in the form filters do, normalized to NFC."""
+    users = [
+        User(id="composed", user_name="\u00c9mile"),
+        User(id="fabrice", user_name="Fabrice"),
+        User(id="decomposed", user_name="E\u0301mile"),
+    ]
+    assert ids(SearchRequest[User](sort_by="userName").sort(users)) == [
+        "fabrice",
+        "composed",
+        "decomposed",
+    ]
+
+
 def test_sort_follows_the_case_of_a_case_exact_string():
     """RFC7644 §3.4.2.3 sorts a case-exact string with its case, upper case first."""
     users = [