scimitar 1.8.1 → 1.10.0

data/app/models/scimitar/resources/mixin.rb

@@ -139,27 +139,31 @@ module Scimitar
     #       # ...
     #       groups: [
     #         {
-    #           list: :users,          # <-- i.e. Team.users,
+    #           list:  :users,         # <-- i.e. Team.users,
     #           using: {
     #             value:   :id,        # <-- i.e. Team.users[n].id
     #             display: :full_name  # <-- i.e. Team.users[n].full_name
     #           },
+    #           class: Team, # Optional; see below
     #           find_with: -> (scim_list_entry) {...} # See below
     #         }
     #       ],
     #       #...
     #     end
     #
-    # The mixing-in class _must+ implement the read accessor identified by the
+    # The mixing-in class _must_ implement the read accessor identified by the
     # value of the "list" key, returning any indexed, Enumerable collection
     # (e.g. an Array or ActiveRecord::Relation instance). The optional key
-    # ":find_with" is defined with a Proc that's passed the SCIM entry at each
+    # ":find_with" is defined with a Proc that is passed the SCIM entry at each
     # list position. It must use this to look up the equivalent entry for
     # association via the write accessor described by the ":list" key. In the
     # example above, "find_with"'s Proc might look at a SCIM entry value which
     # is expected to be a user ID and find that User. The mapped set of User
     # data thus found would be written back with "#users=", due to the ":list"
-    # key declaring the method name ":users".
+    # key declaring the method name ":users". The optional "class" key is
+    # recommended but not really *needed* unless the configuration option
+    # Scimitar::EngineConfiguration::schema_list_from_attribute_mappings is
+    # defined; see documentation of that option for more information.
     #
     # Note that you can only use either:
     #
@@ -176,7 +180,8 @@ module Scimitar
     # == scim_mutable_attributes
     #
     # Define this method to return a Set (preferred) or Array of names of
-    # attributes which may be written in the mixing-in class.
+    # attributes which may be written in the mixing-in class. The names MUST be
+    # expressed as Symbols, *not* Strings.
     #
     # If you return +nil+, it is assumed that +any+ attribute mapped by
     # ::scim_attributes_map which has a write accessor will be eligible for
@@ -204,12 +209,12 @@ module Scimitar
     # Define this method to return a Hash that maps field names you wish to
     # support in SCIM filter queries to corresponding attributes in the in the
     # mixing-in class. If +nil+ then filtering is not supported in the
-    # ResouceController subclass which declares that it maps to the mixing-in
+    # ResourceController subclass which declares that it maps to the mixing-in
     # class. If not +nil+ but a SCIM filter enquiry is made for an unmapped
     # attribute, an 'invalid filter' exception is raised.
     #
     # If using ActiveRecord support in Scimitar::Lists::QueryParser, the mapped
-    # entites are columns and that's expressed in the names of keys described
+    # entities are columns and that's expressed in the names of keys described
     # below; if you have other approaches to searching, these might be virtual
     # attributes or other such constructs rather than columns. That would be up
     # to your non-ActiveRecord's implementation to decide.
@@ -262,8 +267,8 @@ module Scimitar
     # both of the keys 'created' and 'lastModified', as Symbols. The values
     # should be methods that the including method supports which return a
     # creation or most-recently-updated time, respectively. The returned object
-    # mustsupport #iso8601 to convert to a String representation. Example for a
-    # typical ActiveRecord object with standard timestamps:
+    # must support #iso8601 to convert to a String representation. Example for
+    # a typical ActiveRecord object with standard timestamps:
     #
     #     def self.scim_timestamps_map
     #       {
@@ -291,7 +296,7 @@ module Scimitar
         # the result in an instance variable.
         #
         def scim_mutable_attributes
-          @scim_mutable_attributes ||= self.class.scim_mutable_attributes()
+          @scim_mutable_attributes ||= self.class.scim_mutable_attributes()&.map(&:to_sym)
 
           if @scim_mutable_attributes.nil?
             @scim_mutable_attributes = Set.new
@@ -335,18 +340,36 @@ module Scimitar
           @scim_queryable_attributes ||= self.class.scim_queryable_attributes()
         end
 
-        # Render self as a SCIM object using ::scim_attributes_map.
+        # Render self as a SCIM object using ::scim_attributes_map. Fields that
+        # are marked as <tt>returned: 'never'</tt> are excluded.
         #
-        # +location+:: The location (HTTP(S) full URI) of this resource, in the
-        #              domain of the object including this mixin - "your" IDs,
-        #              not the remote SCIM client's external IDs. #url_for is a
-        #              good way to generate this.
+        # +location+::           The location (HTTP(S) full URI) of this
+        #                        resource in the domain of the object including
+        #                        this mixin - "your" IDs, not the remote SCIM
+        #                        client's external IDs. #url_for is a good way
+        #                        to generate this.
         #
-        def to_scim(location:)
+        # +include_attributes+:: The attributes that should be included in the
+        #                        response, in the form of a list of full
+        #                        attribute paths. Schema IDs are not supported.
+        #                        See RFC 7644 section 3.9 and section 3.10 for
+        #                        more. When a collection is given, +nil+ value
+        #                        items are also excluded from the response. If
+        #                        omitted or given an empty collection, all
+        #                        attributes are included.
+        #
+        def to_scim(location:, include_attributes: [])
           map             = self.class.scim_attributes_map()
+          resource_type   = self.class.scim_resource_type()
           timestamps_map  = self.class.scim_timestamps_map() if self.class.respond_to?(:scim_timestamps_map)
-          attrs_hash      = self.to_scim_backend(data_source: self, attrs_map_or_leaf_value: map)
-          resource        = self.class.scim_resource_type().new(attrs_hash)
+          attrs_hash      = self.to_scim_backend(
+            data_source:             self,
+            resource_type:           resource_type,
+            attrs_map_or_leaf_value: map,
+            include_attributes:      include_attributes
+          )
+
+          resource        = resource_type.new(attrs_hash)
           meta_attrs_hash = { location: location }
 
           meta_attrs_hash[:created     ] = self.send(timestamps_map[:created     ])&.iso8601(0) if timestamps_map&.key?(:created)
@@ -373,16 +396,39 @@ module Scimitar
         #
         # Call ONLY for POST or PUT. For PATCH, see #from_scim_patch!.
         #
-        # +scim_hash+:: A Hash that's the result of parsing a JSON payload
-        #               from an inbound POST or PUT request.
+        # Mandatory named parameters:
+        #
+        # +scim_hash+::     A Hash that's the result of parsing a JSON payload
+        #                   from an inbound POST or PUT request.
+        #
+        # Optional named parameters:
+        #
+        # +with_clearing+:: According to RFC 7644 section 3.5.1, PUT operations
+        #                   MAY default or clear any attribute missing from
+        #                   +scim_hash+ as this is deemed "not asserted by the
+        #                   client" (see
+        #                   https://tools.ietf.org/html/rfc7644#section-3.5.1).
+        #                   This parameter controls such behaviour. It defaults
+        #                   to +true+, so clearing is applied - single value
+        #                   attributes are set to +nil+ and arrays are emptied.
+        #                   If +false+, an unusual <b>preservation</b> mode is
+        #                   applied and anything absent from +scim_hash+ will
+        #                   have no impact on the target object (any mapped
+        #                   attributes in the local data model with existing
+        #                   non-nil values will retain those values).
         #
         # Returns 'self', for convenience of e.g. chaining other methods.
         #
-        def from_scim!(scim_hash:)
+        def from_scim!(scim_hash:, with_clearing: true)
           scim_hash.freeze()
           map = self.class.scim_attributes_map().freeze()
 
-          self.from_scim_backend!(attrs_map_or_leaf_value: map, scim_hash_or_leaf_value: scim_hash)
+          self.from_scim_backend!(
+            attrs_map_or_leaf_value: map,
+            scim_hash_or_leaf_value: scim_hash,
+            with_clearing:           with_clearing
+          )
+
           return self
         end
 
@@ -458,32 +504,21 @@ module Scimitar
               ci_scim_hash = { 'root' => ci_scim_hash }.with_indifferent_case_insensitive_access()
             end
 
-            # Handle extension schema. Contributed by @bettysteger and
-            # @MorrisFreeman via:
+            # Split the path into an array of path components, in a way
+            # which is aware of extension schemas. See documentation of
+            # Scimitar::Support::Utilities.path_str_to_array for details.
             #
-            #   https://github.com/RIPAGlobal/scimitar/issues/48
-            #   https://github.com/RIPAGlobal/scimitar/pull/49
-            #
-            # Note the ":" separating the schema ID (URN) from the attribute.
-            # The nature of JSON rendering / other payloads might lead you to
-            # expect a "." as with any complex types, but that's not the case;
-            # see https://tools.ietf.org/html/rfc7644#section-3.10, or
-            # https://tools.ietf.org/html/rfc7644#section-3.5.2 of which in
-            # particular, https://tools.ietf.org/html/rfc7644#page-35.
-            #
-            paths = []
-            self.class.scim_resource_type.extended_schemas.each do |schema|
-              path_str.downcase.split(schema.id.downcase + ':').drop(1).each do |path|
-                paths += [schema.id] + path.split('.')
-              end
-            end
-            paths = path_str.split('.') if paths.empty?
+            paths = ::Scimitar::Support::Utilities.path_str_to_array(
+              self.class.scim_resource_type.extended_schemas,
+              path_str
+            )
 
             self.from_patch_backend!(
               nature:        nature,
               path:          paths,
               value:         value,
-              altering_hash: ci_scim_hash
+              altering_hash: ci_scim_hash,
+              with_attr_map: self.class.scim_attributes_map()
             )
 
             if extract_root
@@ -491,7 +526,7 @@ module Scimitar
             end
           end
 
-          self.from_scim!(scim_hash: ci_scim_hash)
+          self.from_scim!(scim_hash: ci_scim_hash, with_clearing: false)
           return self
         end
 
@@ -509,16 +544,71 @@ module Scimitar
           #                             this is "self" (an instance of the
           #                             class mixing in this module).
           #
+          # +resource_type+::           The resource type carrying the schemas
+          #                             describing the SCIM object. If at the
+          #                             top level when +data_source+ is +self+,
+          #                             this would be sent as
+          #                             <tt>self.class.scim_resource_type()</tt>.
+          #
           # +attrs_map_or_leaf_value+:: The attribute map. At the top level,
           #                             this is from ::scim_attributes_map.
           #
-          def to_scim_backend(data_source:, attrs_map_or_leaf_value:)
+          # +include_attributes+::      The attributes that should be included
+          #                             in the response, in the form of a list
+          #                             of full attribute paths. Schema IDs are
+          #                             not supported. See RFC 7644 section
+          #                             3.9 and section 3.10 for more. When a
+          #                             collection is given, +nil+ value items
+          #                             are also excluded from the response. If
+          #                             omitted or given an empty collection,
+          #                             all attributes are included.
+          #
+          # Internal recursive calls also send:
+          #
+          # +attribute_path+::          Array of path components to the
+          #                             attribute, which can be found through
+          #                             +resource_type+ so that things like the
+          #                             "+returned+" state can be checked.
+          #
+          def to_scim_backend(
+            data_source:,
+            resource_type:,
+            attrs_map_or_leaf_value:,
+            include_attributes:,
+            attribute_path: []
+          )
+            # NOTE EARLY EXIT
+            #
+            return unless scim_attribute_included?(
+              include_attributes: include_attributes,
+              attribute_path:     attribute_path
+            )
+
+            # On assumption of a top-level attributes list, the 'return never'
+            # state is only checked on the recursive call from a Hash type. The
+            # other handled types are assumed to only happen when called
+            # recursively, so no need to check as no such call is made for a
+            # 'return never' attribute.
+            #
             case attrs_map_or_leaf_value
               when Hash # Expected at top-level of any map, or nested within
-                attrs_map_or_leaf_value.each.with_object({}) do |(key, value), hash|
-                  hash[key] = to_scim_backend(data_source: data_source, attrs_map_or_leaf_value: value)
+                result = attrs_map_or_leaf_value.each.with_object({}) do |(key, value), hash|
+                  nested_attribute_path = attribute_path + [key]
+
+                  if resource_type.find_attribute(*nested_attribute_path)&.returned != "never"
+                    hash[key] = to_scim_backend(
+                      data_source:             data_source,
+                      resource_type:           resource_type,
+                      attribute_path:          nested_attribute_path,
+                      attrs_map_or_leaf_value: value,
+                      include_attributes:      include_attributes
+                    )
+                  end
                 end
 
+                result.compact! if include_attributes.any?
+                result
+
               when Array # Static or dynamic mapping against lists in data source
                 built_dynamic_list = false
                 mapped_array = attrs_map_or_leaf_value.map do |value|
@@ -527,14 +617,28 @@ module Scimitar
 
                   elsif value.key?(:match) # Static map
                     static_hash = { value[:match] => value[:with] }
-                    static_hash.merge!(to_scim_backend(data_source: data_source, attrs_map_or_leaf_value: value[:using]))
+                    static_hash.merge!(
+                      to_scim_backend(
+                        data_source:             data_source,
+                        resource_type:           resource_type,
+                        attribute_path:          attribute_path,
+                        attrs_map_or_leaf_value: value[:using],
+                        include_attributes:      include_attributes
+                      )
+                    )
                     static_hash
 
                   elsif value.key?(:list) # Dynamic mapping of each complex list item
                     built_dynamic_list = true
                     list = data_source.public_send(value[:list])
                     list.map do |list_entry|
-                      to_scim_backend(data_source: list_entry, attrs_map_or_leaf_value: value[:using])
+                      to_scim_backend(
+                        data_source:             list_entry,
+                        resource_type:           resource_type,
+                        attribute_path:          attribute_path,
+                        attrs_map_or_leaf_value: value[:using],
+                        include_attributes:      include_attributes
+                      )
                     end
 
                   else # Unknown type, just treat as flat values
@@ -625,6 +729,15 @@ module Scimitar
           #                             read as input source material (left
           #                             hand side of the ASCII art diagram).
           #
+          # +with_clearing+::           If +true+, attributes absent in
+          #                             +scim_hash_or_leaf_value+ but present
+          #                             in +attrs_map_or_leaf_value+ will be
+          #                             cleared (+nil+ or empty array), for PUT
+          #                             ("replace") semantics. If +false+, such
+          #                             missing attribute values are left
+          #                             untouched - whatever mapped value is in
+          #                             +self+ is preserved.
+          #
           # +path+::                    Array of SCIM attribute names giving a
           #                             path into the SCIM schema where
           #                             iteration has reached. Used to find the
@@ -634,6 +747,7 @@ module Scimitar
           def from_scim_backend!(
             attrs_map_or_leaf_value:,
             scim_hash_or_leaf_value:,
+            with_clearing:,
             path: []
           )
             scim_hash_or_leaf_value = scim_hash_or_leaf_value.with_indifferent_case_insensitive_access() if scim_hash_or_leaf_value.is_a?(Hash)
@@ -658,19 +772,43 @@ module Scimitar
                   #   https://github.com/RIPAGlobal/scimitar/issues/48
                   #   https://github.com/RIPAGlobal/scimitar/pull/49
                   #
+                  # Note the shortcoming that attribute names within extensions
+                  # must be unique, as this mechanism basically just pulls out
+                  # extension attributes to the top level, losing what amounts
+                  # to the namespace that the extension schema ID provides.
+                  #
                   attribute_tree = []
                   resource_class.extended_schemas.each do |schema|
-                    attribute_tree << schema.id and break if schema.scim_attributes.any? { |attribute| attribute.name == scim_attribute.to_s }
+                    if schema.scim_attributes.any? { |attribute| attribute.name == scim_attribute.to_s }
+                      attribute_tree << schema.id
+                      break # NOTE EARLY LOOP EXIT
+                    end
                   end
                   attribute_tree << scim_attribute.to_s
 
-                  sub_scim_hash_or_leaf_value = scim_hash_or_leaf_value&.dig(*attribute_tree)
+                  continue_processing = if with_clearing
+                    true
+                  else
+                    most_of_attribute_tree = attribute_tree[...-1]
+                    last_attribute_in_tree = attribute_tree.last
+
+                    if most_of_attribute_tree.empty?
+                      scim_hash_or_leaf_value&.key?(last_attribute_in_tree)
+                    else
+                      scim_hash_or_leaf_value&.dig(*most_of_attribute_tree)&.key?(last_attribute_in_tree)
+                    end
+                  end
 
-                  self.from_scim_backend!(
-                    attrs_map_or_leaf_value: sub_attrs_map_or_leaf_value,
-                    scim_hash_or_leaf_value: sub_scim_hash_or_leaf_value, # May be 'nil'
-                    path:                    path + [scim_attribute]
-                  )
+                  if continue_processing
+                    sub_scim_hash_or_leaf_value = scim_hash_or_leaf_value&.dig(*attribute_tree)
+
+                    self.from_scim_backend!(
+                      attrs_map_or_leaf_value: sub_attrs_map_or_leaf_value,
+                      scim_hash_or_leaf_value: sub_scim_hash_or_leaf_value, # May be 'nil'
+                      with_clearing:           with_clearing,
+                      path:                    path + [scim_attribute]
+                    )
+                  end
                 end
 
               when Array # Static or dynamic maps
@@ -692,6 +830,7 @@ module Scimitar
                     self.from_scim_backend!(
                       attrs_map_or_leaf_value: sub_attrs_map,
                       scim_hash_or_leaf_value: found_source_list_entry, # May be 'nil'
+                      with_clearing:           with_clearing,
                       path:                    path
                     )
 
@@ -747,7 +886,9 @@ module Scimitar
           # +path+::          Operation path, as a series of array entries (so
           #                   an inbound dot-separated path string would first
           #                   be split into an array by the caller). For
-          #                   internal recursive calls, this will
+          #                   internal recursive calls, this will be a subset
+          #                   of array entries from an index somewhere into the
+          #                   top-level array, through to its end.
           #
           # +value+::         The value to apply at the attribute(s) identified
           #                   by +path+. Ignored for 'remove' operations.
@@ -763,7 +904,7 @@ module Scimitar
           # own wrapping Hash with a single key addressing the SCIM object of
           # interest and supply this key as the sole array entry in +path+.
           #
-          def from_patch_backend!(nature:, path:, value:, altering_hash:)
+          def from_patch_backend!(nature:, path:, value:, altering_hash:, with_attr_map:)
             raise 'Case sensitivity violation' unless altering_hash.is_a?(Scimitar::Support::HashWithIndifferentCaseInsensitiveAccess)
 
             # These all throw exceptions if data is not as expected / required,
@@ -774,14 +915,16 @@ module Scimitar
                 nature:        nature,
                 path:          path,
                 value:         value,
-                altering_hash: altering_hash
+                altering_hash: altering_hash,
+                with_attr_map: with_attr_map
               )
             else
               from_patch_backend_traverse!(
                 nature:        nature,
                 path:          path,
                 value:         value,
-                altering_hash: altering_hash
+                altering_hash: altering_hash,
+                with_attr_map: with_attr_map
               )
             end
 
@@ -801,7 +944,7 @@ module Scimitar
           #
           # Happily throws exceptions if data is not as expected / required.
           #
-          def from_patch_backend_traverse!(nature:, path:, value:, altering_hash:)
+          def from_patch_backend_traverse!(nature:, path:, value:, altering_hash:, with_attr_map:)
             raise 'Case sensitivity violation' unless altering_hash.is_a?(Scimitar::Support::HashWithIndifferentCaseInsensitiveAccess)
 
             path_component, filter = extract_filter_from(path_component: path.first)
@@ -847,11 +990,27 @@ module Scimitar
             end
 
             found_data_for_recursion.each do | found_data |
+              attr_map = if path_component.to_sym == :root
+                with_attr_map
+              else
+                with_attr_map[path_component.to_sym]
+              end
+
+              # Static array mappings need us to find the right map entry that
+              # corresponds to the SCIM data at hand and recurse back into the
+              # patch engine with the ":using" attribute map data.
+              #
+              if attr_map.is_a?(Array)
+                array_attr_map = find_matching_static_attr_map(data: found_data, with_attr_map: attr_map)
+                attr_map       = array_attr_map unless array_attr_map.nil?
+              end
+
               self.from_patch_backend!(
                 nature:        nature,
-                path:          path[1..-1],
+                path:          path[1..],
                 value:         value,
-                altering_hash: found_data
+                altering_hash: found_data,
+                with_attr_map: attr_map
               )
             end
           end
@@ -866,7 +1025,7 @@ module Scimitar
           #
           # Happily throws exceptions if data is not as expected / required.
           #
-          def from_patch_backend_apply!(nature:, path:, value:, altering_hash:)
+          def from_patch_backend_apply!(nature:, path:, value:, altering_hash:, with_attr_map:)
             raise 'Case sensitivity violation' unless altering_hash.is_a?(Scimitar::Support::HashWithIndifferentCaseInsensitiveAccess)
 
             path_component, filter = extract_filter_from(path_component: path.first)
@@ -896,11 +1055,48 @@ module Scimitar
 
                 case nature
                   when 'remove'
-                    current_data_at_path[matched_index] = nil
-                    compact_after = true
+                    handled        = false
+                    attr_map_path  = path[..-2] + [path_component]
+                    attr_map_entry = with_attr_map.dig(*attr_map_path.map(&:to_sym))
+
+                    # Deal with arrays specially; static maps require specific
+                    # treatment, but dynamic or actual array values do not.
+                    #
+                    if attr_map_entry.is_a?(Array)
+                      array_attr_map = find_matching_static_attr_map(
+                        data:          matched_hash,
+                        with_attr_map: attr_map_entry
+                      )
+
+                      # Found? Run through the mapped attributes. Anything that
+                      # has an associated model attribute (i.e. some property
+                      # that must be to be written into local data in response
+                      # to the SCIM attribute being changed) is 'removed' by
+                      # setting the corresponding value in "altering_hash" (of
+                      # which "matched_hash" referenced fragment) to "nil".
+                      #
+                      handled = clear_data_for_removal!(
+                        altering_hash: matched_hash,
+                        with_attr_map: array_attr_map
+                      )
+                    end
+
+                    # For dynamic arrays or other value types, we assume that
+                    # just clearing the item from the array or setting its SCIM
+                    # attribute to "nil" will result in an appropriate update
+                    # to the local data model (e.g. by a change in an Rails
+                    # associated collection or clearing a local model attribute
+                    # directly to "nil").
+                    #
+                    if handled == false
+                      current_data_at_path[matched_index] = nil
+                      compact_after = true
+                    end
+
                   when 'replace'
                     matched_hash.reject! { true }
                     matched_hash.merge!(value)
+
                 end
               end
 
@@ -939,11 +1135,30 @@ module Scimitar
                     # at key 'members' with the above, rather than adding.
                     #
                     value.keys.each do | key |
+
+                      # Handle the Azure (Entra) case where keys might use
+                      # dotted paths - see:
+                      #
+                      #   https://github.com/RIPAGlobal/scimitar/issues/123
+                      #
+                      # ...along with keys containing schema IDs - see:
+                      #
+                      #   https://is.docs.wso2.com/en/next/apis/scim2-patch-operations/#add-user-attributes
+                      #
+                      # ...and scroll down to example 3 of "Complex singular
+                      # attributes".
+                      #
+                      subpaths = ::Scimitar::Support::Utilities.path_str_to_array(
+                        self.class.scim_resource_type.extended_schemas,
+                        key
+                      )
+
                       from_patch_backend!(
                         nature:        nature,
-                        path:          path + [key],
+                        path:          path + subpaths,
                         value:         value[key],
-                        altering_hash: altering_hash
+                        altering_hash: altering_hash,
+                        with_attr_map: with_attr_map
                       )
                     end
                   else
@@ -953,8 +1168,14 @@ module Scimitar
                 when 'replace'
                   if path_component == 'root'
                     dot_pathed_value = value.inject({}) do |hash, (k, v)|
-                      hash.deep_merge!(::Scimitar::Support::Utilities.dot_path(k.split('.'), v))
+                      subpaths = ::Scimitar::Support::Utilities.path_str_to_array(
+                        self.class.scim_resource_type.extended_schemas,
+                        k
+                      )
+
+                      hash.deep_merge!(::Scimitar::Support::Utilities.dot_path(subpaths, v))
                     end
+
                     altering_hash[path_component].deep_merge!(dot_pathed_value)
                   else
                     altering_hash[path_component] = value
@@ -1013,8 +1234,8 @@ module Scimitar
                     # integer primary keys, which all end up as strings anyway.
                     #
                     value.each do | value_item |
-                      altering_hash[path_component].delete_if do | item |
-                        if item.is_a?(Hash) && value_item.is_a?(Hash)
+                      altering_hash[path_component].map! do | item |
+                        item_is_matched = if item.is_a?(Hash) && value_item.is_a?(Hash)
                           matched_all = true
                           value_item.each do | value_key, value_value |
                             next if value_key == '$ref'
@@ -1026,10 +1247,55 @@ module Scimitar
                         else
                           item&.to_s == value_item&.to_s
                         end
+
+                        if item_is_matched
+                          handled        = false
+                          attr_map_path  = path[..-2] + [path_component]
+                          attr_map_entry = with_attr_map.dig(*attr_map_path.map(&:to_sym))
+                          array_attr_map = find_matching_static_attr_map(
+                            data:          item,
+                            with_attr_map: attr_map_entry
+                          )
+
+                          handled = clear_data_for_removal!(
+                            altering_hash: item,
+                            with_attr_map: array_attr_map
+                          )
+
+                          handled ? item : nil
+                        else
+                          item
+                        end
+                      end
+
+                      altering_hash[path_component].compact!
+                    end
+
+                  elsif altering_hash[path_component].is_a?(Array)
+                    handled        = false
+                    attr_map_path  = path[..-2] + [path_component]
+                    attr_map_entry = with_attr_map.dig(*attr_map_path.map(&:to_sym))
+
+                    if attr_map_entry.is_a?(Array) # Array mapping
+                      altering_hash[path_component].each do | data_to_check |
+                        array_attr_map = find_matching_static_attr_map(
+                          data:          data_to_check,
+                          with_attr_map: attr_map_entry
+                        )
+
+                        handled = clear_data_for_removal!(
+                          altering_hash: data_to_check,
+                          with_attr_map: array_attr_map
+                        )
                       end
                     end
+
+                    if handled == false
+                      altering_hash[path_component] = []
+                    end
+
                   else
-                    altering_hash.delete(path_component)
+                    altering_hash[path_component] = nil
                   end
 
               end
@@ -1108,6 +1374,200 @@ module Scimitar
             end
           end
 
+          # Static attribute maps are used where SCIM attributes include some
+          # kind of array, but it's not an arbitrary collection (dynamic maps
+          # handle those). Instead, specific matched values inside the SCIM
+          # data are mapped to specific attributes in the local data model.
+          #
+          # A typical example is for e-mails, where the SCIM "type" field in an
+          # array of e-mail addresses might get mapped to detect specific types
+          # of address such as "work" and "home", which happen to be stored
+          # locally in dedicated attributes (e.g. "work_email_address").
+          #
+          # During certain processing operations we end up with a set of data
+          # sent in from some SCIM operation and need to make modifications
+          # (e.g. for a PATCH) that require the attribute map corresponding to
+          # each part of the inbound SCIM data to be known. That's where this
+          # method comes in. Usually, it's not hard to traverse a path of SCIM
+          # data and dig a corresponding path through the attribute map Hash,
+          # except for static arrays. There, we need to know which of the
+          # static map entries matches a piece of SCIM data *from entries* in
+          # the array of SCIM data corresponding to the static map.
+          #
+          # Call here with a piece of SCIM data from an array, along with an
+          # attribute map fragment that must be the Array containing mappings.
+          # Static mapping entries from this are compared with the data and if
+          # a match is found, the sub-attribute map from the static entry's
+          # <tt>:using</tt> key is returned; else +nil+.
+          #
+          # Named parameters are:
+          #
+          # +data+::          A SCIM data entry from a SCIM data array which is
+          #                   mapped via the data given in the +with_attr_map+
+          #                   parameter.
+          #
+          # +with_attr_map+:: The attributes map fragment which must be an
+          #                   Array of mappings for the corresponding array
+          #                   in the SCIM data from which +data+ was drawn.
+          #
+          # For example, if SCIM data consisted of:
+          #
+          #     {
+          #       'emails' => [
+          #         {
+          #           'type' => 'work',
+          #           'value' => 'work_1@test.com'
+          #         },
+          #         {
+          #           'type' => 'work',
+          #           'value' => 'work_2@test.com'
+          #         }
+          #       ]
+          #     }
+          #
+          # ...which was mapped to the local data model using the following
+          # attribute map:
+          #
+          #     {
+          #       emails: [
+          #         { match: 'type', with: 'home', using: { value: :home_email } },
+          #         { match: 'type', with: 'work', using: { value: :work_email } },
+          #       ]
+          #     }
+          #
+          # ...then when it came to processing the SCIM 'emails' entry, one of
+          # the array _entries_ therein would be passed in +data+, while the
+          # attribute map's <tt>:emails</tt> key's value (the _array_ of map
+          # data) would be given in <tt>:with_attr_map</tt>. The first SCIM
+          # array entry matches +work+ so the <tt>:using</tt> part of the map
+          # for that match would be returned:
+          #
+          #     { value: :work_email }
+          #
+          # If there was a SCIM entry with a type of something unrecognised,
+          # such as 'holday', then +nil+ would be returned since there is no
+          # matching attribute map entry.
+          #
+          # Note that the <tt>:with_attr_map</tt> array can contain dynamic
+          # mappings or even be just a simple fixed array - only things that
+          # "look like" static mapping entries are processed (i.e. Hashes with
+          # a Symbol key of <tt>:match</tt> present), with the rest ignored.
+          #
+          def find_matching_static_attr_map(data:, with_attr_map:)
+            matched_map = with_attr_map.find do | static_or_dynamic_mapping |
+
+              # Only interested in Static Array mappings.
+              #
+              if static_or_dynamic_mapping.is_a?(Hash) && static_or_dynamic_mapping.key?(:match)
+
+                attr_to_match  = static_or_dynamic_mapping[:match].to_s
+                value_to_match = static_or_dynamic_mapping[:with]
+                sub_attrs_map  = static_or_dynamic_mapping[:using]
+
+                # If this mapping refers to the matched data at hand,
+                # then we can process it further (see later below.
+                #
+                found = data[attr_to_match] == value_to_match
+
+                # Not found? No static map match perhaps; this could be
+                # because a filter worked on a value which is fixed in
+                # the static map. For example, a filter might check for
+                # emails with "primary true", and the emergence of the
+                # value for "primary" might not be in the data model -
+                # it could be a constant declared in the 'using' part
+                # of a static map. Ugh! Check for that.
+                #
+                unless found
+                  sub_attrs_map.each do | scim_attr, model_attr_or_constant |
+
+                    # Only want constants such as 'true' or 'false'.
+                    #
+                    next if model_attr_or_constant.is_a?(Symbol)
+
+                    # Does the static value match in the source data?
+                    # E.g. a SCIM attribute :primary with value 'true'.
+                    #
+                    if data[scim_attr] == model_attr_or_constant
+                      found = true
+                      break
+                    end
+                  end
+                end
+
+                found
+              else
+                false
+              end
+            end
+
+            return matched_map&.dig(:using)
+          end
+
+          # Related to #find_matching_static_attr_map - often, the reason to
+          # find a static array entry related to some inbound SCIM data is for
+          # a removal operation, where the way to "remove" the data in the
+          # local data model is to set an attribute to "nil". This means you
+          # need to know if there is an attribute writer related to the SCIM
+          # data being removed - and #find_matching_static_attr_map helps.
+          #
+          # With that done, you can call here with the hash data to be changed
+          # and fragment of attribute map that #find_matching_static_attr_map
+          # (or something like it) found.
+          #
+          # +altering_hash+:: The fragment of SCIM data that might be updated
+          #                   with +nil+ to ultimately lead to an atttribute
+          #                   writer identified through +with_attr_map+ being
+          #                   called with that value. This is often the same
+          #                   that was passed in the +data+ attribute in a
+          #                   prior #find_matching_static_attr_map call.
+          #
+          # +with_attr_map::  The map fragment that corresponds exactly to the
+          #                   +altering_hash+ data - e.g. the return value of a
+          #                   prior #find_matching_static_attr_map call.
+          #
+          # Update +altering_hash+ in place if the map finds a relevant local
+          # data model attribute and returns +true+. If no changes are made,
+          # returns +false+.
+          #
+          def clear_data_for_removal!(altering_hash:, with_attr_map:)
+            handled = false
+
+            with_attr_map&.each do | scim_attr, model_attr_or_constant |
+
+              # Only process attribute names, not constants.
+              #
+              next unless model_attr_or_constant.is_a?(Symbol)
+
+              altering_hash[scim_attr] = nil
+              handled                  = true
+            end
+
+            return handled
+          end
+
+          # Related to to_scim_backend, this methods tells whether +attribute_path+
+          # should be included in the current +include_attributes+. This method
+          # implements the attributes request from RFC 7644, section 3.9 and 3.10.
+          #
+          # +include_attributes+::      The attributes that should be included
+          #                             in the response, in the form of a list of
+          #                             full attribute paths. See RFC 7644 section
+          #                             3.9 and section 3.10. An empty collection
+          #                             will include all attributes.
+          #
+          # +attribute_path+::          Array of path components to the attribute,
+          #                             e.g. <tt>["name", "givenName"]</tt>.
+          #
+          def scim_attribute_included?(include_attributes:, attribute_path:)
+            return true unless attribute_path.any? && include_attributes.any?
+
+            full_path = attribute_path.join(".")
+            attribute_included = full_path.start_with?(*include_attributes)
+            will_include_nested = include_attributes.any? { |att| att.start_with?(full_path) }
+
+            attribute_included || will_include_nested
+          end
+
       end # "included do"
     end # "module Mixin"
   end # "module Resources"