feat: locate validation errors with an attribute path

Author: azmeuk

doc/changelog.rst

@@ -21,6 +21,8 @@ Changed
 - :attr:`AttributeBinding.urn <scim2_models.AttributeBinding.urn>` and the error messages
   that quote it spell the attribute as the schema declares it, such as ``userName``, whatever
   case the path used.
+- Validation errors locate the value with an attribute path, such as ``emails[1].value``, and no
+  longer expose internal names of pydantic.
 
 Security
 ^^^^^^^^

scim2_models/messages/bulk.py

@@ -226,7 +226,7 @@ class BulkRequest(_ResourceParameterized, Message, Generic[ResourceT]):
     returned."""
 
     operations: Annotated[list[BulkOperation[ResourceT]] | None, Required.true] = Field(
-        None, serialization_alias="Operations"
+        None, alias="Operations"
     )
     """Defines operations within a bulk job."""
 
@@ -243,7 +243,7 @@ class BulkResponse(_ResourceParameterized, Message, Generic[ResourceT]):
     __schema__ = URN("urn:ietf:params:scim:api:messages:2.0:BulkResponse")
 
     operations: Annotated[list[BulkOperation[ResourceT]] | None, Required.true] = Field(
-        None, serialization_alias="Operations"
+        None, alias="Operations"
     )
     """Defines operations within a bulk job."""
 

scim2_models/messages/error.py

@@ -44,6 +44,46 @@ def _scim_type_of(error: Mapping[str, Any]) -> str | None:
     return "invalidValue"
 
 
+def _is_urn(part: str | int | None) -> bool:
+    return isinstance(part, str) and part.casefold().startswith("urn:")
+
+
+def _attribute_path(loc: Sequence[str | int]) -> str:
+    """Write the location of a Pydantic error as a SCIM attribute path.
+
+    Sub-attributes follow their attribute after a dot, and the attributes of an
+    extension follow its schema URN after a colon, as in the notation of
+    :rfc:`RFC7644 §3.10 <7644#section-3.10>`. SCIM has no notation for one
+    value of a multi-valued attribute, so its index in the payload is written
+    in brackets, e.g. ``emails[1].value``.
+
+    Pydantic also names the member of a union it tried. A member is a schema
+    of its own, such as ``function-after[...]``, or the schema URN of a
+    resource in a list. No attribute name can hold brackets or parentheses
+    (:rfc:`RFC7643 §2.1 <7643#section-2.1>`), and no extension directly
+    follows an index, so both are left out.
+    """
+    path = ""
+    previous: str | int | None = None
+    for part in loc:
+        if isinstance(part, int):
+            path += f"[{part}]"
+        elif "[" in part or "(" in part:
+            continue
+        elif _is_urn(part) and isinstance(previous, int):
+            # The extensions of the resource may follow its own schema URN.
+            previous = None
+            continue
+        elif not path:
+            path = part
+        elif _is_urn(previous):
+            path += f":{part}"
+        else:
+            path += f".{part}"
+        previous = part
+    return path
+
+
 class Error(Message):
     """Representation of SCIM API errors.
 
@@ -85,8 +125,8 @@ def from_validation_error(cls, error: Mapping[str, Any]) -> "Error":
                 detail=error["msg"],
             )
 
-        loc = ", ".join(str(loc) for loc in error["loc"])
-        detail = f"{error['msg']}: {loc}" if loc else error["msg"]
+        path = _attribute_path(error["loc"])
+        detail = f"{error['msg']}: {path}" if path else error["msg"]
         return cls(status=400, scim_type=_scim_type_of(error), detail=detail)
 
     @classmethod

scim2_models/messages/list_response.py

@@ -75,7 +75,7 @@ def validate_cursor_chars(cls, value: str | None) -> str | None:
             raise InvalidCursorException().as_pydantic_error()
         return value
 
-    resources: list[AnyResource] | None = Field(None, serialization_alias="Resources")
+    resources: list[AnyResource] | None = Field(None, alias="Resources")
     """A multi-valued list of complex objects containing the requested
     resources."""
 

scim2_models/messages/patch_op.py

@@ -179,7 +179,7 @@ def __class_getitem__(cls, item: Any) -> Any:
     __schema__ = URN("urn:ietf:params:scim:api:messages:2.0:PatchOp")
 
     operations: Annotated[list[PatchOperation[ResourceT]] | None, Required.true] = (
-        Field(None, serialization_alias="Operations")
+        Field(None, alias="Operations")
     )
     """The body of an HTTP PATCH request MUST contain the attribute
     "Operations", whose value is an array of one or more PATCH operations."""

tests/test_exceptions.py

@@ -6,18 +6,23 @@
 from pydantic import ValidationError
 from pydantic import field_validator
 
+from scim2_models import BulkResponse
 from scim2_models import Context
+from scim2_models import EnterpriseUser
 from scim2_models import Error
 from scim2_models import ExpiredCursorException
+from scim2_models import Group
 from scim2_models import InvalidCountException
 from scim2_models import InvalidCursorException
 from scim2_models import InvalidFilterException
 from scim2_models import InvalidPathException
 from scim2_models import InvalidSyntaxException
 from scim2_models import InvalidValueException
 from scim2_models import InvalidVersionException
+from scim2_models import ListResponse
 from scim2_models import MutabilityException
 from scim2_models import NoTargetException
+from scim2_models import PatchOp
 from scim2_models import PathNotFoundException
 from scim2_models import SCIMException
 from scim2_models import SensitiveException
@@ -616,3 +621,108 @@ def test_from_error_without_status():
     error = Error(scim_type="uniqueness", detail="Duplicate userName")
     exc = SCIMException.from_error(error)
     assert exc.status == 409
+
+
+ENTERPRISE_USER_SCHEMA = "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
+USER_SCHEMA = "urn:ietf:params:scim:schemas:core:2.0:User"
+
+
+def first_error_detail(model, payload, scim_ctx):
+    """Return the detail of the first SCIM error a payload raises."""
+    with pytest.raises(ValidationError) as exc_info:
+        model.model_validate(payload, scim_ctx=scim_ctx)
+    return Error.from_validation_errors(exc_info.value)[0].detail
+
+
+@pytest.mark.parametrize(
+    "model,payload,scim_ctx,path",
+    [
+        (
+            User,
+            {"userName": "bjensen", "name": {"givenName": 3}},
+            Context.RESOURCE_CREATION_REQUEST,
+            "name.givenName",
+        ),
+        (
+            User,
+            {
+                "userName": "bjensen",
+                "emails": [{"value": "a@example.com"}, {"value": 3}],
+            },
+            Context.RESOURCE_CREATION_REQUEST,
+            "emails[1].value",
+        ),
+        (
+            User[EnterpriseUser],
+            {"userName": "bjensen", ENTERPRISE_USER_SCHEMA: {"manager": {"value": 3}}},
+            Context.RESOURCE_CREATION_REQUEST,
+            f"{ENTERPRISE_USER_SCHEMA}:manager.value",
+        ),
+        (
+            ListResponse[User | Group],
+            {"Resources": [{"schemas": [USER_SCHEMA], "id": "1", "userName": 3}]},
+            Context.RESOURCE_QUERY_RESPONSE,
+            "Resources[0].userName",
+        ),
+        (
+            ListResponse[User[EnterpriseUser] | Group],
+            {
+                "Resources": [
+                    {
+                        "schemas": [USER_SCHEMA, ENTERPRISE_USER_SCHEMA],
+                        "id": "1",
+                        "userName": "bjensen",
+                        ENTERPRISE_USER_SCHEMA: {"employeeNumber": 3},
+                    }
+                ]
+            },
+            Context.RESOURCE_QUERY_RESPONSE,
+            f"Resources[0].{ENTERPRISE_USER_SCHEMA}:employeeNumber",
+        ),
+        (
+            BulkResponse[User],
+            {
+                "Operations": [
+                    {
+                        "method": "POST",
+                        "status": 201,
+                        "location": "https://example.com/v2/Users/1",
+                        "response": {"schemas": [USER_SCHEMA], "userName": 3},
+                    }
+                ]
+            },
+            Context.BULK_RESPONSE,
+            "Operations[0].response.userName",
+        ),
+    ],
+)
+def test_the_detail_of_an_error_locates_it_with_an_attribute_path(
+    model, payload, scim_ctx, path
+):
+    """Sub-attributes follow a dot, extension attributes their schema URN and a colon, values their index.
+
+    The members of the unions pydantic tried are not part of the payload, and
+    are left out.
+    """
+    assert first_error_detail(model, payload, scim_ctx) == (
+        f"Input should be a valid string: {path}"
+    )
+
+
+def test_the_detail_of_an_error_at_the_root_of_a_payload_carries_no_path():
+    """An error on the payload itself has no attribute to point at."""
+    with pytest.raises(ValidationError) as exc_info:
+        User.model_validate("not an object", scim_ctx=Context.RESOURCE_CREATION_REQUEST)
+    error = Error.from_validation_errors(exc_info.value)[0]
+    assert error.detail == "Input should be a valid dictionary or instance of User"
+
+
+@pytest.mark.parametrize("key", ["Operations", "operations", "OPERATIONS"])
+def test_message_attributes_keep_their_case_insensitive_names(key):
+    """The Operations of a message are named as RFC 7644 spells them, and read whatever their case."""
+    patch = PatchOp[User].model_validate(
+        {key: [{"op": "replace", "path": "nickName", "value": "Babs"}]},
+        scim_ctx=Context.RESOURCE_PATCH_REQUEST,
+    )
+    assert patch.operations[0].value == "Babs"
+    assert "Operations" in patch.model_dump(scim_ctx=Context.RESOURCE_PATCH_REQUEST)

tests/test_path.py

@@ -103,7 +103,7 @@ def test_a_malformed_path_in_a_message_answers_invalid_path():
         )
 
     reported = raised.value.errors()[0]
-    assert reported["loc"] == ("operations", 0, "path")
+    assert reported["loc"] == ("Operations", 0, "path")
     error = Error.from_validation_error(reported)
     assert error.status == 400
     assert error.scim_type == "invalidPath"