feat: replace() now copies readOnly and preserves immutable fields

Enforce RFC 7644 §3.5.1 PUT semantics: readOnly fields are copied
from the original resource, and omitted immutable fields are preserved
instead of being nulled out.

Author: azmeuk

doc/changelog.rst

@@ -1,6 +1,13 @@
 Changelog
 =========
 
+[0.6.10] - Unreleased
+---------------------
+
+Fixed
+^^^^^
+- replace copies readOnly and preserves immutable fields
+
 [0.6.9] - 2026-04-07
 --------------------
 

doc/guides/_examples/django_example.py

@@ -176,7 +176,6 @@ def put(self, request, app_record):
         except SCIMException as error:
             return scim_exception_error(error)
 
-        replacement.id = existing_user.id
         updated_record = from_scim_user(replacement)
         try:
             save_record(updated_record)

doc/guides/_examples/fastapi_example.py

@@ -186,7 +186,6 @@ async def replace_user(
     existing_user = to_scim_user(app_record, resource_location(request, app_record))
     replacement.replace(existing_user)
 
-    replacement.id = existing_user.id
     updated_record = from_scim_user(replacement)
     save_record(updated_record)
 

doc/guides/_examples/flask_example.py

@@ -177,7 +177,6 @@ def replace_user(app_record):
     )
     replacement.replace(existing_user)
 
-    replacement.id = existing_user.id
     updated_record = from_scim_user(replacement)
     save_record(updated_record)
 

scim2_models/base.py

@@ -413,7 +413,7 @@ def check_replacement_request_mutability(
             and original is not None
         ):
             try:
-                obj._check_immutable_fields(original)
+                obj._apply_replace_constraints(original)
             except MutabilityException as exc:
                 raise exc.as_pydantic_error() from exc
         return obj
@@ -461,30 +461,47 @@ def check_primary_attribute_uniqueness(self, info: ValidationInfo) -> Self:
 
         return self
 
-    def _check_immutable_fields(self, original: Self) -> None:
-        """Check that immutable fields have not been modified compared to *original*.
+    def _apply_replace_constraints(self, original: Self) -> None:
+        """Enforce RFC 7644 §3.5.1 replace (PUT) semantics.
 
-        Recursively checks nested single-valued complex attributes.
+        - ``readOnly`` fields are copied from *original* unconditionally.
+        - ``immutable`` fields are copied from *original* when absent from
+          ``self``; a :class:`~scim2_models.MutabilityException` is raised
+          when the value differs.
+
+        Recursively applies to nested single-valued complex attributes.
         """
         from .attributes import is_complex_attribute
 
         for field_name in type(self).model_fields:
             mutability = type(self).get_field_annotation(field_name, Mutability)
-            if mutability == Mutability.immutable and getattr(
-                original, field_name
-            ) != getattr(self, field_name):
-                raise MutabilityException(attribute=field_name, mutability="immutable")
+            original_val = getattr(original, field_name)
+
+            if mutability == Mutability.read_only:
+                # RFC 7644 §3.5.1: "readOnly" values provided SHALL be ignored.
+                setattr(self, field_name, original_val)
+            elif mutability == Mutability.immutable:
+                self_val = getattr(self, field_name)
+                if self_val is None and original_val is not None:
+                    # RFC 7643 §7: "SHALL NOT be updated" — omitting an
+                    # immutable field is not a request to clear it.
+                    setattr(self, field_name, original_val)
+                elif self_val != original_val:
+                    # RFC 7644 §3.5.1: input values MUST match.
+                    raise MutabilityException(
+                        attribute=field_name, mutability="immutable"
+                    )
 
             attr_type = type(self).get_field_root_type(field_name)
             if (
                 attr_type
                 and is_complex_attribute(attr_type)
                 and not type(self).get_field_multiplicity(field_name)
             ):
-                original_val = getattr(original, field_name)
-                replacement_val = getattr(self, field_name)
-                if original_val is not None and replacement_val is not None:
-                    replacement_val._check_immutable_fields(original_val)
+                original_sub = getattr(original, field_name)
+                replacement_sub = getattr(self, field_name)
+                if original_sub is not None and replacement_sub is not None:
+                    replacement_sub._apply_replace_constraints(original_sub)
 
     def _set_complex_attribute_urns(self) -> None:
         """Navigate through attributes and sub-attributes of type ComplexAttribute, and mark them with a '_attribute_urn' attribute.

scim2_models/resources/resource.py

@@ -154,18 +154,16 @@ class Resource(ScimObject, Generic[AnyExtension]):
     """A complex attribute containing resource metadata."""
 
     def replace(self, original: Self) -> None:
-        """Verify that no immutable field has been modified compared to *original*.
+        """Apply :rfc:`RFC 7644 §3.5.1 <7644#section-3.5.1>` replace (PUT) semantics.
 
-        Intended to be called after parsing a PUT request body, to enforce
-        :rfc:`RFC 7644 §3.5.1 <7644#section-3.5.1>`: if one or more values
-        are already set for an immutable attribute, the input values MUST match.
-
-        Recursively checks nested single-valued complex attributes.
+        ``readOnly`` fields are copied from *original*.
+        ``immutable`` fields are preserved from *original* when absent,
+        or checked for equality when present.
 
         :param original: The original resource state to compare against.
         :raises MutabilityException: If an immutable field value differs.
         """
-        self._check_immutable_fields(original)
+        self._apply_replace_constraints(original)
 
     @classmethod
     def __class_getitem__(cls, item: Any) -> type["Resource[Any]"]:

tests/test_model_validation.py

@@ -145,7 +145,7 @@ def test_validate_replacement_request_mutability():
 
     Attributes marked as:
     - Mutability.immutable raise a ValidationError if different than the 'original' item.
-    - Mutability.read_only are ignored
+    - Mutability.read_only are copied from the original
     """
     original = MutResource(read_only="y", read_write="y", write_only="y", immutable="y")
     with pytest.warns(DeprecationWarning, match="original"):
@@ -160,6 +160,7 @@ def test_validate_replacement_request_mutability():
             original=original,
         ) == MutResource(
             schemas=["org:example:MutResource"],
+            read_only="y",
             readWrite="x",
             writeOnly="x",
             immutable="y",
@@ -286,6 +287,49 @@ def test_replace_ignores_readwrite_changes():
     original = MutResource(read_write="y")
     replacement = MutResource(read_write="x")
     replacement.replace(original)
+    assert replacement.read_write == "x"
+
+
+def test_replace_copies_read_only_from_original():
+    """Replace copies readOnly fields from the original resource."""
+    original = MutResource(read_only="server-value")
+    replacement = MutResource(read_only="client-value")
+    replacement.replace(original)
+    assert replacement.read_only == "server-value"
+
+
+def test_replace_copies_read_only_none_from_original():
+    """Replace copies readOnly fields even when the original value is None."""
+    original = MutResource(read_only=None)
+    replacement = MutResource(read_only="client-value")
+    replacement.replace(original)
+    assert replacement.read_only is None
+
+
+def test_replace_preserves_immutable_when_absent():
+    """Replace copies immutable fields from original when absent in replacement."""
+    original = MutResource(immutable="y")
+    replacement = MutResource(immutable=None)
+    replacement.replace(original)
+    assert replacement.immutable == "y"
+
+
+def test_replace_copies_read_only_in_nested_complex_attribute():
+    """Replace copies readOnly sub-attributes from original in nested complex attributes."""
+
+    class Sub(ComplexAttribute):
+        read_only: Annotated[str | None, Mutability.read_only] = None
+        read_write: Annotated[str | None, Mutability.read_write] = None
+
+    class Super(Resource):
+        schemas: Annotated[list[str], Required.true] = ["org:example:Super"]
+        sub: Sub | None = None
+
+    original = Super(sub=Sub(read_only="server", read_write="old"))
+    replacement = Super(sub=Sub(read_only="client", read_write="new"))
+    replacement.replace(original)
+    assert replacement.sub.read_only == "server"
+    assert replacement.sub.read_write == "new"
 
 
 def test_original_parameter_emits_deprecation_warning():