feat: attribute inclusion/exclusions overhaul

- ListResponse accepts attributes and excluded_attributes parameters
- Extract attributes/excluded_attributes logic from SearchRequest to
  ResponseParameters
- attributes and excluded_attributes can be comma separated strings

Author: azmeuk

doc/changelog.rst

@@ -1,6 +1,15 @@
 Changelog
 =========
 
+[0.7.0] - Unreleased
+--------------------
+
+Added
+^^^^^
+- :class:`~scim2_models.ListResponse` ``model_dump`` and ``model_dump_json`` now accept ``attributes`` and ``excluded_attributes`` parameters. :issue:`59`
+- New :class:`~scim2_models.ResponseParameters` model for :rfc:`RFC7644 §3.9 <7644#section-3.9>` ``attributes`` and ``excludedAttributes`` query parameters. :class:`~scim2_models.SearchRequest` inherits from it.
+- :class:`~scim2_models.ResponseParameters` and :class:`~scim2_models.SearchRequest` accept comma-separated strings for ``attributes`` and ``excludedAttributes``.
+
 [0.6.6] - 2026-03-12
 --------------------
 

doc/guides/_examples/django_example.py

@@ -13,6 +13,7 @@
 from scim2_models import Error
 from scim2_models import ListResponse
 from scim2_models import PatchOp
+from scim2_models import ResponseParameters
 from scim2_models import SearchRequest
 from scim2_models import UniquenessException
 from scim2_models import User
@@ -86,9 +87,18 @@ class UserView(View):
     """Handle GET, PATCH and DELETE on one SCIM user resource."""
 
     def get(self, request, app_record):
+        try:
+            req = ResponseParameters.model_validate(request.GET.dict())
+        except ValidationError as error:
+            return scim_validation_error(error)
+
         scim_user = to_scim_user(app_record)
         return scim_response(
-            scim_user.model_dump_json(scim_ctx=Context.RESOURCE_QUERY_RESPONSE)
+            scim_user.model_dump_json(
+                scim_ctx=Context.RESOURCE_QUERY_RESPONSE,
+                attributes=req.attributes,
+                excluded_attributes=req.excluded_attributes,
+            )
         )
 
     def delete(self, request, app_record):
@@ -126,9 +136,10 @@ class UsersView(View):
 
     def get(self, request):
         try:
-            req = SearchRequest.model_validate(request.GET)
+            req = SearchRequest.model_validate(request.GET.dict())
         except ValidationError as error:
             return scim_validation_error(error)
+
         all_records = list_records()
         page = all_records[req.start_index_0 : req.stop_index_0]
         resources = [to_scim_user(record) for record in page]
@@ -139,7 +150,11 @@ def get(self, request):
             resources=resources,
         )
         return scim_response(
-            response.model_dump_json(scim_ctx=Context.RESOURCE_QUERY_RESPONSE)
+            response.model_dump_json(
+                scim_ctx=Context.RESOURCE_QUERY_RESPONSE,
+                attributes=req.attributes,
+                excluded_attributes=req.excluded_attributes,
+            )
         )
 
     def post(self, request):

doc/guides/_examples/flask_example.py

@@ -10,6 +10,7 @@
 from scim2_models import Error
 from scim2_models import ListResponse
 from scim2_models import PatchOp
+from scim2_models import ResponseParameters
 from scim2_models import SearchRequest
 from scim2_models import UniquenessException
 from scim2_models import User
@@ -84,9 +85,14 @@ def handle_value_error(error):
 @bp.get("/Users/<user:app_record>")
 def get_user(app_record):
     """Return one SCIM user."""
+    req = ResponseParameters.model_validate(request.args.to_dict())
     scim_user = to_scim_user(app_record)
     return (
-        scim_user.model_dump_json(scim_ctx=Context.RESOURCE_QUERY_RESPONSE),
+        scim_user.model_dump_json(
+            scim_ctx=Context.RESOURCE_QUERY_RESPONSE,
+            attributes=req.attributes,
+            excluded_attributes=req.excluded_attributes,
+        ),
         HTTPStatus.OK,
     )
 # -- get-user-end --
@@ -128,7 +134,7 @@ def delete_user(app_record):
 @bp.get("/Users")
 def list_users():
     """Return one page of users as a SCIM ListResponse."""
-    req = SearchRequest.model_validate(request.args)
+    req = SearchRequest.model_validate(request.args.to_dict())
     all_records = list_records()
     page = all_records[req.start_index_0 : req.stop_index_0]
     resources = [to_scim_user(record) for record in page]
@@ -139,7 +145,11 @@ def list_users():
         resources=resources,
     )
     return (
-        response.model_dump_json(scim_ctx=Context.RESOURCE_QUERY_RESPONSE),
+        response.model_dump_json(
+            scim_ctx=Context.RESOURCE_QUERY_RESPONSE,
+            attributes=req.attributes,
+            excluded_attributes=req.excluded_attributes,
+        ),
         HTTPStatus.OK,
     )
 # -- list-users-end --

doc/guides/django.rst

@@ -104,8 +104,9 @@ Single resource
 ^^^^^^^^^^^^^^^
 
 ``UserView`` handles ``GET``, ``PATCH`` and ``DELETE`` on ``/Users/<id>``.
-For ``GET``, convert the native record to a SCIM resource and serialize with
-:attr:`~scim2_models.Context.RESOURCE_QUERY_RESPONSE`.
+For ``GET``, parse query parameters with :class:`~scim2_models.ResponseParameters` to honour the
+``attributes`` and ``excludedAttributes`` query parameters, convert the native record to a
+SCIM resource, and serialize with :attr:`~scim2_models.Context.RESOURCE_QUERY_RESPONSE`.
 For ``DELETE``, remove the record and return an empty 204 response.
 For ``PATCH``, validate the payload with :attr:`~scim2_models.Context.RESOURCE_PATCH_REQUEST`,
 apply it with :meth:`~scim2_models.PatchOp.patch` (generic, works with any resource type),
@@ -121,9 +122,13 @@ Collection
 ^^^^^^^^^^
 
 ``UsersView`` handles ``GET /Users`` and ``POST /Users``.
-For ``GET``, parse pagination parameters with :class:`~scim2_models.SearchRequest`, slice
-the store, then wrap the page in a :class:`~scim2_models.ListResponse` serialized with
+For ``GET``, parse pagination and filtering parameters with
+:class:`~scim2_models.SearchRequest`, slice the store, then wrap the page in a
+:class:`~scim2_models.ListResponse` serialized with
 :attr:`~scim2_models.Context.RESOURCE_QUERY_RESPONSE`.
+``req.attributes`` and ``req.excluded_attributes`` are passed to
+:meth:`~scim2_models.ListResponse.model_dump_json` to apply the ``attributes`` and
+``excludedAttributes`` query parameters to each embedded resource.
 For ``POST``, validate the creation payload with
 :attr:`~scim2_models.Context.RESOURCE_CREATION_REQUEST`, persist the record, then serialize
 with :attr:`~scim2_models.Context.RESOURCE_CREATION_RESPONSE`.

doc/guides/flask.rst

@@ -79,8 +79,11 @@ any other collection.
 GET /Users/<id>
 ^^^^^^^^^^^^^^^
 
-Convert the native record to a SCIM resource with your mapping helper, then serialize with
-:attr:`~scim2_models.Context.RESOURCE_QUERY_RESPONSE`.
+Parse query parameters with :class:`~scim2_models.ResponseParameters`, convert the native
+record to a SCIM resource with your mapping helper, then serialize with
+:attr:`~scim2_models.Context.RESOURCE_QUERY_RESPONSE`, forwarding
+``req.attributes`` and ``req.excluded_attributes`` so the response only includes the
+requested fields.
 
 .. literalinclude:: _examples/flask_example.py
    :language: python
@@ -116,9 +119,12 @@ convert back to native and persist, then serialize the result with
 GET /Users
 ^^^^^^^^^^
 
-Parse pagination parameters with :class:`~scim2_models.SearchRequest`, slice the store
-accordingly, then wrap the page in a :class:`~scim2_models.ListResponse` serialized with
-:attr:`~scim2_models.Context.RESOURCE_QUERY_RESPONSE`.
+Parse pagination and filtering parameters with :class:`~scim2_models.SearchRequest`, slice
+the store accordingly, then wrap the page in a :class:`~scim2_models.ListResponse` serialized
+with :attr:`~scim2_models.Context.RESOURCE_QUERY_RESPONSE`.
+Pass ``req.attributes`` and ``req.excluded_attributes`` to
+:meth:`~scim2_models.ListResponse.model_dump_json` so that the ``attributes`` and
+``excludedAttributes`` query parameters are applied to each embedded resource.
 
 .. literalinclude:: _examples/flask_example.py
    :language: python

scim2_models/__init__.py

@@ -27,6 +27,7 @@
 from .messages.message import Message
 from .messages.patch_op import PatchOp
 from .messages.patch_op import PatchOperation
+from .messages.response_parameters import ResponseParameters
 from .messages.search_request import SearchRequest
 from .path import URN
 from .path import Path
@@ -121,6 +122,7 @@
     "Required",
     "Resource",
     "ResourceType",
+    "ResponseParameters",
     "Returned",
     "Role",
     "SCIMException",

scim2_models/messages/list_response.py

@@ -2,15 +2,20 @@
 from typing import Generic
 
 from pydantic import Field
+from pydantic import FieldSerializationInfo
+from pydantic import SerializerFunctionWrapHandler
 from pydantic import ValidationInfo
 from pydantic import ValidatorFunctionWrapHandler
+from pydantic import field_serializer
 from pydantic import model_validator
 from pydantic_core import PydanticCustomError
 from typing_extensions import Self
 
 from ..context import Context
 from ..path import URN
+from ..path import Path
 from ..resources.resource import AnyResource
+from ..scim_object import ScimObject
 from .message import Message
 from .message import _GenericMessageMetaclass
 
@@ -67,3 +72,96 @@ def check_results_number(
             )
 
         return obj
+
+    @field_serializer("resources", mode="wrap")
+    def _serialize_resources(
+        self,
+        value: list[AnyResource] | None,
+        handler: SerializerFunctionWrapHandler,
+        info: FieldSerializationInfo,
+    ) -> Any:
+        """Apply attributes/excluded_attributes filtering to each embedded resource."""
+        if not value:
+            return handler(value)
+
+        attributes = info.context.get("scim_list_attributes") if info.context else None
+        excluded_attributes = (
+            info.context.get("scim_list_excluded_attributes") if info.context else None
+        )
+
+        if not attributes and not excluded_attributes:
+            return handler(value)
+
+        scim_ctx = info.context.get("scim") if info.context else None
+        return [
+            resource.model_dump(
+                scim_ctx=scim_ctx,
+                attributes=attributes or None,
+                excluded_attributes=excluded_attributes or None,
+            )
+            for resource in value
+        ]
+
+    def _prepare_model_dump(
+        self,
+        scim_ctx: Context | None = Context.DEFAULT,
+        attributes: list[str | Path[Any]] | None = None,
+        excluded_attributes: list[str | Path[Any]] | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        kwargs = super()._prepare_model_dump(scim_ctx, **kwargs)
+        if attributes:
+            kwargs["context"]["scim_list_attributes"] = attributes
+        if excluded_attributes:
+            kwargs["context"]["scim_list_excluded_attributes"] = excluded_attributes
+        return kwargs
+
+    def model_dump(
+        self,
+        *args: Any,
+        scim_ctx: Context | None = Context.DEFAULT,
+        attributes: list[str | Path[Any]] | None = None,
+        excluded_attributes: list[str | Path[Any]] | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Create a model representation that can be included in SCIM messages by using Pydantic :code:`BaseModel.model_dump`.
+
+        :param scim_ctx: If a SCIM context is passed, some default values of
+            Pydantic :code:`BaseModel.model_dump` are tuned to generate valid SCIM
+            messages. Pass :data:`None` to get the default Pydantic behavior.
+        :param attributes: A multi-valued list of strings indicating the names of resource
+            attributes to return in the response, overriding the set of attributes that
+            would be returned by default. Invalid values are ignored.
+        :param excluded_attributes: A multi-valued list of strings indicating the names of resource
+            attributes to be removed from the default set of attributes to return. Invalid values are ignored.
+        """
+        dump_kwargs = self._prepare_model_dump(
+            scim_ctx, attributes, excluded_attributes, **kwargs
+        )
+        if scim_ctx:
+            dump_kwargs.setdefault("mode", "json")
+        return super(ScimObject, self).model_dump(*args, **dump_kwargs)
+
+    def model_dump_json(
+        self,
+        *args: Any,
+        scim_ctx: Context | None = Context.DEFAULT,
+        attributes: list[str | Path[Any]] | None = None,
+        excluded_attributes: list[str | Path[Any]] | None = None,
+        **kwargs: Any,
+    ) -> str:
+        """Create a JSON model representation that can be included in SCIM messages by using Pydantic :code:`BaseModel.model_dump_json`.
+
+        :param scim_ctx: If a SCIM context is passed, some default values of
+            Pydantic :code:`BaseModel.model_dump` are tuned to generate valid SCIM
+            messages. Pass :data:`None` to get the default Pydantic behavior.
+        :param attributes: A multi-valued list of strings indicating the names of resource
+            attributes to return in the response, overriding the set of attributes that
+            would be returned by default. Invalid values are ignored.
+        :param excluded_attributes: A multi-valued list of strings indicating the names of resource
+            attributes to be removed from the default set of attributes to return. Invalid values are ignored.
+        """
+        dump_kwargs = self._prepare_model_dump(
+            scim_ctx, attributes, excluded_attributes, **kwargs
+        )
+        return super(ScimObject, self).model_dump_json(*args, **dump_kwargs)

scim2_models/messages/response_parameters.py

@@ -0,0 +1,41 @@
+from typing import Any
+
+from pydantic import field_validator
+from pydantic import model_validator
+
+from ..base import BaseModel
+from ..path import Path
+
+
+class ResponseParameters(BaseModel):
+    """:rfc:`RFC7644 §3.9 <7644#section-3.9>` ``attributes`` and ``excludedAttributes`` query parameters."""
+
+    attributes: list[Path[Any]] | None = None
+    """A multi-valued list of strings indicating the names of resource
+    attributes to return in the response, overriding the set of attributes that
+    would be returned by default."""
+
+    excluded_attributes: list[Path[Any]] | None = None
+    """A multi-valued list of strings indicating the names of resource
+    attributes to be removed from the default set of attributes to return."""
+
+    @field_validator("attributes", "excluded_attributes", mode="before")
+    @classmethod
+    def split_comma_separated(cls, value: Any) -> Any:
+        """Split comma-separated strings into lists.
+
+        :rfc:`RFC7644 §3.9 <7644#section-3.9>` defines these as
+        comma-separated query parameter values.
+        """
+        if isinstance(value, str):
+            return [v.strip() for v in value.split(",") if v.strip()]
+        return value
+
+    @model_validator(mode="after")
+    def attributes_validator(self) -> "ResponseParameters":
+        if self.attributes and self.excluded_attributes:
+            raise ValueError(
+                "'attributes' and 'excluded_attributes' are mutually exclusive"
+            )
+
+        return self

scim2_models/messages/search_request.py

@@ -2,30 +2,18 @@
 from typing import Any
 
 from pydantic import field_validator
-from pydantic import model_validator
 
 from ..path import URN
 from ..path import Path
 from .message import Message
+from .response_parameters import ResponseParameters
 
 
-class SearchRequest(Message):
-    """SearchRequest object defined at RFC7644.
-
-    https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.3
-    """
+class SearchRequest(Message, ResponseParameters):
+    """SearchRequest object defined at :rfc:`RFC7644 §3.4.3 <7644#section-3.4.3>`."""
 
     __schema__ = URN("urn:ietf:params:scim:api:messages:2.0:SearchRequest")
 
-    attributes: list[Path[Any]] | None = None
-    """A multi-valued list of strings indicating the names of resource
-    attributes to return in the response, overriding the set of attributes that
-    would be returned by default."""
-
-    excluded_attributes: list[Path[Any]] | None = None
-    """A multi-valued list of strings indicating the names of resource
-    attributes to be removed from the default set of attributes to return."""
-
     filter: str | None = None
     """The filter string used to request a subset of resources."""
 
@@ -66,15 +54,6 @@ def count_floor(cls, value: int | None) -> int | None:
         """
         return None if value is None else max(0, value)
 
-    @model_validator(mode="after")
-    def attributes_validator(self) -> "SearchRequest":
-        if self.attributes and self.excluded_attributes:
-            raise ValueError(
-                "'attributes' and 'excluded_attributes' are mutually exclusive"
-            )
-
-        return self
-
     @property
     def start_index_0(self) -> int | None:
         """The 0 indexed start index."""