@@ -8,6 +8,7 @@
 from scim2_models import AuthenticationScheme
 from scim2_models import Bulk
 from scim2_models import ChangePassword
+from scim2_models import ComplexAttribute
 from scim2_models import CaseExact
 from scim2_models import ETag
 from scim2_models import Filter
@@ -83,13 +84,7 @@ def sort_resources(resources, sort_by, sort_order=None):
     descending = sort_order == SearchRequest.SortOrder.descending
 
     def key(resource):
-        value = sort_by.get(resource, strict=False)
-        if isinstance(value, list):
-            # "resources are sorted by the value of the primary attribute, if
-            # any, or else the first value in the list, if any."
-            primary = next((each for each in value if each.primary), None)
-            entry = primary or (value[0] if value else None)
-            value = entry.value if entry else None
+        value = sort_value(resource, sort_by)
         if isinstance(value, str) and not case_exact:
             value = value.casefold()
         # "if there is no data for the specified sortBy value, they are sorted
@@ -98,6 +93,40 @@ def key(resource):
         return (value is None, value if value is not None else "")
 
     return sorted(resources, key=key, reverse=descending)
+
+
+def sort_value(resource, sort_by):
+    """Return the single value a resource is ordered by.
+
+    A path crossing a multi-valued attribute designates the sub-attribute of
+    every entry, where an order needs one value per resource, so the entry is
+    picked first and the sub-attribute read from it.
+
+    :param resource: The resource to read.
+    :param sort_by: The ``sortBy`` query parameter, resolved by its request.
+    """
+    sub_field_name = sort_by.field_name if len(sort_by.parts) > 1 else None
+    attribute = sort_by
+    if sub_field_name is not None:
+        attribute = type(sort_by)(str(sort_by).rsplit(".", 1)[0])
+    value = attribute.get(resource, strict=False)
+
+    if attribute.is_multivalued:
+        entries = value or []
+        # "resources are sorted by the value of the primary attribute, if any,
+        # or else the first value in the list, if any."
+        primary = next(
+            (entry for entry in entries if getattr(entry, "primary", None)), None
+        )
+        value = primary if primary is not None else (entries[0] if entries else None)
+        if sub_field_name is None and isinstance(value, ComplexAttribute):
+            # RFC7643 §2.4 holds the significant value of a complex entry in a
+            # ``value`` sub-attribute, where a scalar entry is the value itself.
+            sub_field_name = "value"
+
+    if value is None or sub_field_name is None:
+        return value
+    return getattr(value, sub_field_name, None)
 # -- sorting-end --
 
 
 
@@ -54,6 +54,12 @@ follows: a string attribute is compared without its case unless it is annotated
 the value of its ``primary`` entry, or the first one; and a resource with no value for the
 attribute comes last when ascending, first when descending.
 
+The second is why the value is not read straight off the path. ``emails.value`` designates the
+value of *every* entry, where an order wants one value per resource, so ``sort_value`` picks
+the entry before reading the sub-attribute from it. That makes ``sortBy=emails`` the same query
+as ``sortBy=emails.value``, :rfc:`RFC7643 §2.4 <7643#section-2.4>` holding the significant value
+of a complex entry in its ``value`` sub-attribute, where a scalar entry is that value itself.
+
 .. literalinclude:: _examples/integrations.py
    :language: python
    :caption: Ordering a collection
 
@@ -6,6 +6,13 @@
 django = pytest.importorskip("django")
 fastapi = pytest.importorskip("fastapi")
 
+from doc.guides._examples.integrations import sort_resources  # noqa: E402
+from doc.guides._examples.integrations import sort_value  # noqa: E402
+from scim2_models import EnterpriseUser  # noqa: E402
+from scim2_models import InvalidPathException  # noqa: E402
+from scim2_models import SearchRequest  # noqa: E402
+from scim2_models import User  # noqa: E402
+
 
 def create_flask_app():
     from flask import Flask
@@ -176,6 +183,120 @@ def sorted_names(query):
         "Zoe@example.com",
     ]
 
+    # A sub-attribute of a multi-valued attribute is read from the entry the
+    # order picks, and only one user carries an email.
+    assert sorted_names("sortBy=emails.value")[0] == "bjensen@example.com"
+
+
+def sorting_users(emails_by_id):
+    """Build users carrying the emails each id maps to."""
+    return [
+        User[EnterpriseUser](id=user_id, user_name=user_id, emails=emails)
+        for user_id, emails in emails_by_id.items()
+    ]
+
+
+def sorting_order(resources, attribute, sort_order=None):
+    """Return the ids a ``sortBy`` puts the resources in."""
+    request = SearchRequest[User[EnterpriseUser]](
+        sort_by=attribute, sort_order=sort_order
+    )
+    return [
+        resource.id
+        for resource in sort_resources(resources, request.sort_by, sort_order)
+    ]
+
+
+def sorting_key(resource, attribute):
+    """Return the single value a ``sortBy`` orders a resource by."""
+    request = SearchRequest[User[EnterpriseUser]](sort_by=attribute)
+    return sort_value(resource, request.sort_by)
+
+
+@pytest.mark.parametrize("attribute", ["emails", "emails.value"])
+def test_sorting_reads_the_primary_entry_of_a_multivalued_attribute(attribute):
+    """The entry marked ``primary`` decides the order, not the first one.
+
+    Ordering on the first entry instead would put ``1`` ahead of ``2``, since
+    ``a@example.com`` precedes ``m@example.com``.
+    """
+    resources = sorting_users(
+        {
+            "1": [
+                User.Emails(value="a@example.com"),
+                User.Emails(value="z@example.com", primary=True),
+            ],
+            "2": [User.Emails(value="m@example.com")],
+        }
+    )
+    assert sorting_order(resources, attribute) == ["2", "1"]
+
+
+def test_sorting_reads_a_sub_attribute_from_the_primary_entry():
+    """A path naming a sub-attribute reads it from the entry the order picked.
+
+    Reading the first entry instead would put ``2`` ahead of ``1``, ``other``
+    preceding ``work``.
+    """
+    resources = sorting_users(
+        {
+            "1": [
+                User.Emails(value="a@example.com", type="work"),
+                User.Emails(value="z@example.com", type="home", primary=True),
+            ],
+            "2": [User.Emails(value="m@example.com", type="other")],
+        }
+    )
+    assert sorting_order(resources, "emails.type") == ["1", "2"]
+
+
+def test_sorting_falls_back_to_the_first_entry_without_a_primary():
+    """An attribute marking no entry primary is ordered by its first one."""
+    resources = sorting_users(
+        {
+            "1": [
+                User.Emails(value="z@example.com"),
+                User.Emails(value="a@example.com"),
+            ],
+            "2": [User.Emails(value="m@example.com")],
+        }
+    )
+    assert sorting_order(resources, "emails.value") == ["2", "1"]
+
+
+def test_sorting_an_unassigned_multivalued_attribute():
+    """A resource carrying no entry comes last ascending and first descending."""
+    resources = sorting_users({"1": None, "2": [User.Emails(value="m@example.com")]})
+    assert sorting_order(resources, "emails.value") == ["2", "1"]
+    assert sorting_order(resources, "emails.value", "descending") == ["1", "2"]
+
+
+def test_sorting_a_scalar_multivalued_attribute_reads_the_entry_itself():
+    """A scalar entry is the value, where a complex one holds it in a sub-attribute."""
+    resource = sorting_users({"1": [User.Emails(value="m@example.com")]})[0]
+    assert sorting_key(resource, "schemas") == User.__schema__
+
+
+def test_sorting_an_attribute_of_an_extension_left_unset():
+    """An extension that is not set holds no value to order by."""
+    resource = sorting_users({"1": None})[0]
+    urn = "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department"
+    assert sorting_key(resource, urn) is None
+
+    resource[EnterpriseUser] = EnterpriseUser(department="Tour Operations")
+    assert sorting_key(resource, urn) == "Tour Operations"
+
+
+def test_sorting_a_request_that_named_no_resource_type():
+    """The helper orders by a resolved attribute, which an unparameterised request has none of.
+
+    A request naming the type it serves cannot reach here: an attribute the
+    model does not declare is refused when the request is built.
+    """
+    resources = sorting_users({"1": None})
+    with pytest.raises(InvalidPathException):
+        sort_resources(resources, SearchRequest(sort_by="userName").sort_by)
+
 
 def test_django_example_smoke():
     from django.conf import settings