scimitar 2.8.0 → 2.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 207cb3e880d58e44ed4c995fd85e165a4a5890ff2974cef418ed605cf4ddba0b
-  data.tar.gz: b1aade94993912f93f783e64b1142447b6d2394f1e9fccd1fc8708116af8542b
+  metadata.gz: '083949bb1e8b8d0afb8e62a87245a0f05189b05669e49eb8b5e3f8fa3af277e6'
+  data.tar.gz: 46a3f0af432f0980280ed8cc8f5c0309bc36f30c15673f9da650f8225f0f406d
 SHA512:
-  metadata.gz: 9c9ecf7480dd0a18df82ad0c2b18b9122540d13c44a9bc7a5a2e8d1b5fe8091faa1d57c2fa7791c7509e4736ded919c5dde6c7ff5a52252ef05c5eac9a057c5d
-  data.tar.gz: 3153843636fca6bcf4d2b719eef31d32188b9f1c2b2a4f645f76302bd0be316454a941fb1d50f315cf5ec6118d5553e46eff83c92aecf168152d0d9620ad56d9
+  metadata.gz: 6d10c2377f023f1b3201148bd57813296b1746d64e738838410045a128a10c980ac675c3a7474b56848d2cfe97ab2421d07bfa1ada5512890bfa08bfa2556f82
+  data.tar.gz: 5ff25a1f64a5bccf0ee2289223d31f8bc6b8636586bf09f1903e0b5824aed483d0dba60d9f7736bdc20c5c71ef6858ab38529eee6ff2e00aae20d0b18cb5d647

data/README.md

@@ -457,7 +457,9 @@ You can extend schema with custom data by defining an extension class and callin
 * Must call `super` in `def initialize`, providing data as shown in the example below
 * Must define class methods for `::id` and `::scim_attributes`
 
-The `::id` class method defines a unique schema ID that is used to namespace payloads or paths in JSON responses describing extended resources, JSON payloads creating them or PATCH paths modifying them. The SCIM RFCs would refer to this as the URN. For example, we might choose to use the [RFC-defined User extension schema](https://tools.ietf.org/html/rfc7643#section-4.3) to define a couple of extra fields our User model happens to support:
+The `::id` class method defines a unique schema ID that is used to namespace payloads or paths in JSON responses describing extended resources, JSON payloads creating them or PATCH paths modifying them. The RFCs require this to be a URN ([see RFC 2141](https://tools.ietf.org/html/rfc2141)). Your extension's ID URN must be globally unique. Depending on your expected use case, you should review the [IANA registration considerations that RFC 7643 describes](https://tools.ietf.org//html/rfc7643#section-10) and definitely review the [syntactic structure declaration therein](https://tools.ietf.org/html/rfc7643#section-10.2.1) (`urn:ietf:params:scim:{type}:{name}{:other}`).
+
+For example, we might choose to use the [RFC-defined User extension schema](https://tools.ietf.org/html/rfc7643#section-4.3) to define a couple of extra fields our User model happens to support:
 
 ```ruby
 class UserEnterpriseExtension < Scimitar::Schema::Base
@@ -582,6 +584,23 @@ And write to it like this:
 }
 ```
 
+### Helping with auto-discovery
+
+If you have an API consumer entity querying your Scimitar-based SCIM API provider endpoint and want to enable a degree of auto-discovery for that entity, then depending on your implementation, there may be customisations you wish to make.
+
+#### Default resources
+
+By default, Scimitar advertises (via things like [the `/Schemas` endpoint](https://tools.ietf.org/html/rfc7644#section-4)) support for both a `User` and `Group` resource, but if you (say) only support a `User` concept, you override the default using code such as this in your `config/initializers/scimitar.rb` file:
+
+```ruby
+Rails.application.config.to_prepare do
+  Scimitar::Engine::set_default_resources([Scimitar::Resources::User])
+  # ...other Scimitar configuration / initialisation code...
+end
+```
+
+
+
 ## Security
 
 One vital feature of SCIM is its authorisation and security model. The best resource I've found to describe this in any detail is [section 2 of the protocol RFC, 7644](https://tools.ietf.org/html/rfc7644#section-2).
@@ -600,8 +619,6 @@ Often, you'll find that bearer tokens are in use by SCIM API consumers, but the
 
 ### Specification versus implementation
 
-* The `name` complex type of a User has `givenName` and `familyName` fields which [the RFC 7643 core schema](https://tools.ietf.org/html/rfc7643#section-8.7.1) describes as optional. Scimitar marks these as required, in the belief that most user synchronisation scenarios between clients and a Scimitar-based provider would require at least those names for basic user management on the provider side, in conjunction with the in-spec-required `userName` field. That's only if the whole `name` type is given at all - at the top level, this itself remains optional per spec, but if you're going to bother specifying names at all, Scimitar wants at least those two pieces of data.
-
 * Several complex types for User contain the same set of `value`, `display`, `type` and `primary` fields, all used in synonymous ways.
 
   - The `value` field - which is e.g. an e-mail address or phone number - is described as optional by [the RFC 7643 core schema](https://tools.ietf.org/html/rfc7643#section-8.7.1), also using "SHOULD" rather than "MUST" in field descriptions elsewhere. Scimitar marks this as required by default, since there's not much point being sent (say) an e-mail section which has entries that don't provide the e-mail address. Some services might send `null` values here regardless so, if you need to be able to accept such data, you can set [engine configuration option `optional_value_fields_required`](https://github.com/RIPAGlobal/scimitar/blob/main/config/initializers/scimitar.rb) to `false`.
@@ -620,6 +637,8 @@ Often, you'll find that bearer tokens are in use by SCIM API consumers, but the
 
 * [RFC 7644 indicates](https://tools.ietf.org/html/rfc7644#page-35) that a resource might only return its core schema in the `schemas` attribute if it was created without any extension fields used. Only if e.g. a subsequent `PATCH` operation added data provided by extension schema, would that extension also appear in `schemas`. This behaviour is extremely difficult to implement and Scimitar does not try - it will always return a resource's core schema and any/all defined extension schemas in the `schemas` array at all times.
 
+* As noted earlier, extension schema attribute names must be unique across your entire combined schema, regardless of schema IDs (URNs) used.
+
 If you believe choices made in this section may be incorrect, please [create a GitHub issue](https://github.com/RIPAGlobal/scimitar/issues/new) describing the problem.
 
 ### Omissions
@@ -632,20 +651,6 @@ If you believe choices made in this section may be incorrect, please [create a G
 
   It's very strange just specifying `emails co...`, since this is an Array which contains complex types. Is the filter there meant to try and match every attribute of the nested types in all array entries? I.e. if `type` happened to contain `example.com`, is that meant to match? It's strongly implied, because the next part of the filter specifically says `emails.value`. Again, we have to reach a little and assume that `emails.value` means "in _any_ of the objects in the `emails` Array, match all things where `value` contains `example.org`. It seems likely that this is a specification error and both of the specifiers should be `emails.value`.
 
-  Adding even more complexity - the specification shows filters _which include filters within them_. In the same way that PATCH operations use paths to identify attributes not just by name, but by filter matches within collections - e.g. `emails[type eq "work"]`, for all e-mail objects inside the `emails` array with a `type` attribute that has a value of `work`) - so also can a filter _contain a filter_, which isn't supported. So, this [example from the RFC](https://tools.ietf.org/html/rfc7644#page-23) is not supported by Scimitar:
-
-  - `filter=userType eq "Employee" and emails[type eq "work" and value co "@example.com"]`
-
-  Another filter shows a potential workaround:
-
-  - `filter=userType eq "Employee" and (emails.type eq "work")`
-
-  ...which is just a match on `emails.type`, so if you have a queryable attribute mapping defined for `emails.type`, that would become queryable. Likewise, you could rewrite the more complex prior example thus:
-
-  - `filter=userType eq "Employee" and emails.type eq "work" and emails.value co "@example.com"`
-
-  ...so adding a mapping for `emails.value` would then allow a database query to be constructed.
-
 * Currently filtering for lists is always matched case-insensitive regardless of schema declarations that might indicate otherwise, for `eq`, `ne`, `co`, `sw` and `ew` operators; for greater/less-thank style filters, case is maintained with simple `>`, `<` etc. database operations in use. The standard Group and User schema have `caseExact` set to `false` for just about anything readily queryable, so this hopefully would only ever potentially be an issue for custom schema.
 
 * As an exception to the above, attributes `id`, `externalId` and `meta.*` are matched case-sensitive. Filters that use `eq` on such attributes will end up a comparison using `=` rather than e.g. `ILIKE` (arising from https://github.com/RIPAGlobal/scimitar/issues/36).

data/app/controllers/scimitar/schemas_controller.rb

@@ -12,8 +12,368 @@ module Scimitar
         hash
       end
 
-      render json: schemas_by_id[params[:name]] || schemas
+      list = if params.key?(:name)
+        [ schemas_by_id[params[:name]] ]
+      else
+        schemas
+      end
+
+      # Now we either have a simple render method, or a complex one.
+      #
+      schemas_to_render = if Scimitar.engine_configuration.schema_list_from_attribute_mappings.empty?
+        list
+      else
+        self.redraw_schema_list_using_mappings(list)
+      end
+
+      render(json: {
+        schemas: [
+            'urn:ietf:params:scim:api:messages:2.0:ListResponse'
+        ],
+        totalResults: schemas_to_render.size,
+        startIndex:   1,
+        itemsPerPage: schemas_to_render.size,
+        Resources:    schemas_to_render
+      })
     end
 
+    # =========================================================================
+    # PRIVATE INSTANCE METHODS
+    # =========================================================================
+    #
+    private
+
+      # Given a list of schema *instances*, find all Scimitar::Resources::Mixin
+      # inclusions to obtain classes with a ::scim_resource_type implementation
+      # that is invoked to get at the associated Scimitar resource class; each
+      # resource class then describes the schema it uses; the list is filtered
+      # to include only those found schemas. Then, for each, use the discovered
+      # class' attribute maps to walk the schema attribute tree alongside the
+      # map and render only mapped attributes. This is done via calling down to
+      # ::redraw_schema_using_mappings for each remaining schema in the list.
+      #
+      # An array of new schema data is returned.
+      #
+      # +list+:: Array of schema instances to examine.
+      #
+      def redraw_schema_list_using_mappings(list)
+
+        # Iterate over the configured model classes to build a mapping from
+        # Scimitar schema class to an array of one or more model classes that
+        # seem to use it. This is to detect the error condition wherein some
+        # schema gets used more than once, leading to multiple possible
+        # attribute map choices.
+        #
+        classes_using_scimitar_mixin = Scimitar.engine_configuration.schema_list_from_attribute_mappings
+        schema_to_resource_map       = {}
+
+        classes_using_scimitar_mixin.each do | model_class |
+          resource_class = model_class.scim_resource_type()
+          schemas        = resource_class.extended_schemas + [resource_class.schema]
+
+          schemas.each do | schema_class |
+            schema_to_resource_map[schema_class] ||= []
+            schema_to_resource_map[schema_class] <<  model_class
+          end
+        end
+
+        # Take the schema list and map to rewritten versions based on finding
+        # out which of the above resource classes use a given schema and then
+        # walking this schema's attribute tree while comparing against the
+        # resource class's attribute map. Unmapped attributes are removed. The
+        # reality of resource class attribute mutability might give different
+        # answers for the corresponding schema attribute's mutability; for any
+        # custom schema we'd expect a match, but for core schema where local
+        # resources don't quite work to spec, at least the /Schemas endpoint
+        # can try to reflect reality and aid auto-discovery.
+        #
+        redrawn_list = list.map do | schema_instance |
+          resource_classes_using_schema = schema_to_resource_map[schema_instance.class]
+
+          if resource_classes_using_schema.nil?
+            next # NOTE EARLY LOOP RESTART (schema not used by a resource)
+          elsif resource_classes_using_schema.size > 1
+            raise "Cannot infer attribute map for engine configuration 'schema_list_from_attribute_mappings: true' because multiple resource classes use schema '#{schema_instance.class.name}': #{resource_classes_using_schema.map(&:name).join(', ')}"
+          end
+
+          found_class = classes_using_scimitar_mixin.find do | class_using_scimitar_mixin |
+            resource_class = class_using_scimitar_mixin.scim_resource_type()
+
+            resource_class.schema == schema_instance.class ||
+            resource_class.extended_schemas.include?(schema_instance.class)
+          end
+
+          rebuilt_schema_instance = if found_class
+            redraw_schema_using_mappings(
+              original_schema_instance: schema_instance,
+              instance_including_mixin: found_class.new
+            )
+          else
+            nil
+          end
+
+          rebuilt_schema_instance
+        end
+
+        redrawn_list.compact!
+        redrawn_list
+      end
+
+      # "Redraw" a schema, by walking its attribute tree alongside a related
+      # resource class's attribute map. Only mapped attributes are included.
+      # The mapped model is checked for a read accessor and write ability is
+      # determined via Scimitar::Resources::Mixin#scim_mutable_attributes. This
+      # gives the actual read/write ability of the mapped attribute; if the
+      # schema's declared mutability differs, the *most restrictive* is chosen.
+      # For example, if the schema says read-write but the mapped model only
+      # has read ability, then "readOnly" is used. Conversely, if the schema
+      # says read-only but the mapped model has read-write, the schema's
+      # "readOnly" is chosen instead as the source of truth.
+      #
+      # See the implementation's comments for a table describing exactly how
+      # all mutability conflict cases are resolved.
+      #
+      # The returned schema instance may be a full or partial duplicate of the
+      # one given on input - some or all attributes and/or sub-attributes may
+      # have been duplicated due to e.g. mutability differences. Do not assume
+      # or rely upon this as a caller.
+      #
+      # Mandatory named parameters for external callers are:
+      #
+      # +original_schema_instance+::   The Scimitar::Schema::Base subclass
+      #                                schema *instance* that is to be examined
+      #                                and possibly "redrawn".
+      #
+      # +instance_including_mixin+::   Instance of the model class including
+      #                                Scimitar::Resources::Mixin, providing
+      #                                the attribute map to be examined.
+      #
+      # Named parameters used internally for recursive calls are:
+      #
+      # +scim_attributes_map+::        The fragment of the attribute map found
+      #                                from +instance_including_mixin+'s class
+      #                                initially, which is relevant to the
+      #                                current recursion level. E.g. it might
+      #                                be the sub-attributes map of "name",
+      #                                for things like a "familyName" mapping.
+      #
+      # +schema_attributes+::          An array of schema attributes for the
+      #                                current recursion level, corresponding
+      #                                to +scim_attributes_map+.
+      #
+      # +rebuilt_attribute_array+::    Redrawn schema attributes are collected
+      #                                into this array, which is altered in
+      #                                place. It is usually a 'subAttributes'
+      #                                property of a schema attribute that's
+      #                                provoked recursion in order to examine
+      #                                and rebuild its sub-attributes directly.
+      #
+      def redraw_schema_using_mappings(
+        original_schema_instance:,
+        instance_including_mixin:,
+
+        scim_attributes_map:     nil,
+        schema_attributes:       nil,
+        rebuilt_attribute_array: nil
+      )
+        schema_attributes   ||= original_schema_instance.scim_attributes
+        scim_attributes_map ||= instance_including_mixin
+          .class
+          .scim_attributes_map()
+          .with_indifferent_case_insensitive_access()
+
+        rebuilt_schema_instance = nil
+
+        if rebuilt_attribute_array.nil?
+          rebuilt_schema_instance                 = self.duplicate_attribute(original_schema_instance)
+          rebuilt_schema_instance.scim_attributes = []
+          rebuilt_attribute_array                 = rebuilt_schema_instance.scim_attributes
+        end
+
+        schema_attributes.each do | schema_attribute |
+          if schema_attribute.multiValued && schema_attribute.subAttributes&.any?
+            mapped_multivalue_attribute = scim_attributes_map[schema_attribute.name]
+
+            # We expect either an array in the attribute map to correspond with
+            # a multivalued schema attribute, or nothing. If we get some other
+            # non-Array, not-nil thing, it's just ignored.
+            #
+            if mapped_multivalue_attribute.is_a?(Array)
+
+              # A single-entry array with "list using" semantics, for a
+              # collection of an artbirary number of same-class items - e.g.
+              # Groups to which a User belongs.
+              #
+              # If this is an up-to-date mapping, there's a "class" entry that
+              # tells us what the collection is compromised of. If not, then we
+              # check for ActiveRecord collections as a fallback and if that is
+              # the case here, can use reflection to try and find the class. If
+              # all else fails, we drop to generic schema for the collection.
+              #
+              if mapped_multivalue_attribute.first&.dig(:list)
+                associated_resource_class = mapped_multivalue_attribute.first[:class]
+
+                if (
+                  associated_resource_class.nil? &&
+                  instance_including_mixin.is_a?(ActiveRecord::Base)
+                )
+                  associated_resource_class = instance_including_mixin
+                    .class
+                    .reflect_on_association(mapped_multivalue_attribute.first[:list])
+                    &.klass
+                end
+
+                if associated_resource_class.nil? || ! associated_resource_class.include?(Scimitar::Resources::Mixin)
+                  rebuilt_attribute_array << schema_attribute
+                else
+                  rebuilt_schema_attribute = self.duplicate_attribute(schema_attribute)
+                  rebuilt_schema_attribute.subAttributes = []
+                  rebuilt_attribute_array << rebuilt_schema_attribute
+
+                  redraw_schema_using_mappings(
+                    original_schema_instance: original_schema_instance,
+                    instance_including_mixin: associated_resource_class.new,
+                    scim_attributes_map:      mapped_multivalue_attribute.first[:using],
+                    schema_attributes:        schema_attribute.subAttributes,
+                    rebuilt_attribute_array:  rebuilt_schema_attribute.subAttributes
+                  )
+                end
+
+              # A one-or-more entry array with "match with" semantics, to match
+              # discrete mapped items with a particular value in a particular
+              # field - e.g. an e-mail of type "work" mapping the SCIM "value"
+              # to a local attribute of "work_email_address".
+              #
+              # Mutability or supported attributes here might vary per matched
+              # type. There's no way for SCIM schema to represent that so we
+              # just merge all the "using" mappings together, in order of array
+              # appearance, and have that combined attribute map treated as the
+              # data the schema response will use.
+              #
+              elsif mapped_multivalue_attribute.first&.dig(:match)
+                union_of_mappings = {}
+
+                mapped_multivalue_attribute.each do | mapped_multivalue_attribute_description |
+                  union_of_mappings.merge!(mapped_multivalue_attribute_description[:using])
+                end
+
+                rebuilt_schema_attribute = self.duplicate_attribute(schema_attribute)
+                rebuilt_schema_attribute.subAttributes = []
+                rebuilt_attribute_array << rebuilt_schema_attribute
+
+                redraw_schema_using_mappings(
+                  original_schema_instance: original_schema_instance,
+                  instance_including_mixin: instance_including_mixin,
+                  scim_attributes_map:      union_of_mappings,
+                  schema_attributes:        schema_attribute.subAttributes,
+                  rebuilt_attribute_array:  rebuilt_schema_attribute.subAttributes
+                )
+              end
+            end
+
+          elsif schema_attribute.subAttributes&.any?
+            mapped_subattributes = scim_attributes_map[schema_attribute.name]
+
+            if mapped_subattributes.is_a?(Hash)
+              rebuilt_schema_attribute = self.duplicate_attribute(schema_attribute)
+              rebuilt_schema_attribute.subAttributes = []
+              rebuilt_attribute_array << rebuilt_schema_attribute
+
+              redraw_schema_using_mappings(
+                original_schema_instance: original_schema_instance,
+                instance_including_mixin: instance_including_mixin,
+                scim_attributes_map:      mapped_subattributes,
+                schema_attributes:        schema_attribute.subAttributes,
+                rebuilt_attribute_array:  rebuilt_schema_attribute.subAttributes
+              )
+            end
+
+          else
+            mapped_attribute = scim_attributes_map[schema_attribute.name]
+
+            unless mapped_attribute.nil?
+              rebuilt_schema_attribute = self.duplicate_attribute(schema_attribute)
+              has_mapped_reader        = true
+              has_mapped_writer        = false
+
+              if mapped_attribute.is_a?(String) || mapped_attribute.is_a?(Symbol)
+                has_mapped_reader = instance_including_mixin.respond_to?(mapped_attribute)
+                has_mapped_writer = instance_including_mixin.scim_mutable_attributes().include?(mapped_attribute.to_sym)
+              end
+
+              # The schema is taken as the primary source of truth, leading to
+              # a matrix of "do we override it or not?" based on who is the
+              # more limited. When both have the same mutability there is no
+              # more work to do, so we just need to consider differences:
+              #
+              # Actual class support   Schema says   Result
+              # =============================================================
+              # readWrite              readOnly      readOnly  (schema wins)
+              # readWrite              writeOnly     writeOnly (schema wins)
+              # readOnly               readWrite     readOnly  (class wins)
+              # writeOnly              readWrite     writeOnly (class wins)
+              #
+              # Those cases are easy. But there are gnarly cases too, where we
+              # have no good answer and the class's mapped implementation is in
+              # essence broken compared to the schema. Since it is not useful
+              # to insist on the schema's not-reality version, the class wins.
+              #
+              # Actual class support   Schema says   Result
+              # ====================== =======================================
+              # readOnly               writeOnly     readOnly  (class "wins")
+              # writeOnly              readOnly      writeOnly (class "wins")
+
+              schema_attribute_mutability = schema_attribute.mutability.downcase
+
+              if has_mapped_reader && has_mapped_writer
+                #
+                # Read-write Nothing to do. Schema always "wins" by matching or
+                # being more restrictive than the class's actual abilities.
+
+              elsif has_mapped_reader && ! has_mapped_writer
+                #
+                # Read-only. Class is more restrictive if schema is 'readWrite'
+                # or if there's the broken clash of schema 'writeOnly'.
+                #
+                if schema_attribute_mutability == 'readwrite' || schema_attribute_mutability == 'writeonly'
+                  rebuilt_schema_attribute.mutability = 'readOnly'
+                end
+
+              elsif has_mapped_writer && ! has_mapped_reader
+                #
+                # Opposite to the above case.
+                #
+                if schema_attribute_mutability == 'readwrite' || schema_attribute_mutability == 'readonly'
+                  rebuilt_schema_attribute.mutability = 'writeOnly'
+                end
+
+                # ...else we cannot fathom how this class works - it appears to
+                # have no read or write accessor for the mapped attribute. Keep
+                # the schema's declaration as-is.
+                #
+              end
+
+              rebuilt_attribute_array << rebuilt_schema_attribute
+            end
+          end
+        end
+
+        return rebuilt_schema_instance # (meaningless except for topmost call)
+      end
+
+      # Small helper that duplicates Scimitar::Schema::Attribute instances, but
+      # then removes their 'errors' collection which otherwise gets initialised
+      # to an empty value and is rendered as if part of the schema (which isn't
+      # a valid entry in a SCIM schema representation).
+      #
+      # +schema_attribute+:: Scimitar::Schema::Attribute to be duplicated.
+      #                      A renderable duplicate is returned.
+      #
+      def duplicate_attribute(schema_attribute)
+        duplicated_schema_attribute = schema_attribute.dup()
+        duplicated_schema_attribute.remove_instance_variable('@errors')
+        duplicated_schema_attribute
+      end
+
   end
 end

data/app/models/scimitar/engine_configuration.rb

@@ -14,6 +14,7 @@ module Scimitar
       :application_controller_mixin,
       :exception_reporter,
       :optional_value_fields_required,
+      :schema_list_from_attribute_mappings,
     )
 
     def initialize(attributes = {})
@@ -22,7 +23,8 @@ module Scimitar
       # Set defaults that may be overridden by the initializer.
       #
       defaults = {
-        optional_value_fields_required: true
+        optional_value_fields_required:      true,
+        schema_list_from_attribute_mappings: []
       }
 
       super(defaults.merge(attributes))

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

@@ -35,14 +35,45 @@ module Scimitar
         @errors = ActiveModel::Errors.new(self)
       end
 
+      # Scimitar has at present a general limitation in handling schema IDs,
+      # which just involves stripping them and requiring attributes across all
+      # extension schemas to be overall unique.
+      #
+      # This method takes an options payload for the initializer and strips out
+      # *recognised* schema IDs, so that the resulting attribute data matches
+      # the resource attribute map.
+      #
+      # +attributes+:: Attributes to assign via initializer; typically a POST
+      #                payload of attributes that has been run through Rails
+      #                strong parameters for safety.
+      #
+      # Returns a new object of the same class as +options+ with recognised
+      # schema IDs removed.
+      #
       def flatten_extension_attributes(options)
-        flattened = options.dup
-        self.class.extended_schemas.each do |extended_schema|
-          if extension_attrs = flattened.delete(extended_schema.id)
-            flattened.merge!(extension_attrs)
+        flattened             = options.class.new
+        lower_case_schema_ids = self.class.extended_schemas.map do | schema |
+          schema.id.downcase()
+        end
+
+        options.each do | key, value |
+          path = Scimitar::Support::Utilities::path_str_to_array(
+            self.class.extended_schemas,
+            key
+          )
+
+          if path.first.include?(':') && lower_case_schema_ids.include?(path.first.downcase)
+            path.shift()
+          end
+
+          if path.empty?
+            flattened.merge!(value)
+          else
+            flattened[path.join('.')] = value
           end
         end
-        flattened
+
+        return flattened
       end
 
       # Can be used to extend an existing resource type's schema. For example:

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

@@ -139,11 +139,12 @@ 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
     #         }
     #       ],
@@ -159,7 +160,10 @@ module Scimitar
     # 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
@@ -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

data/config/initializers/scimitar.rb

@@ -106,6 +106,47 @@ Rails.application.config.to_prepare do # (required for >= Rails 7 / Zeitwerk)
     # whatever that means for you receiving system in your model code.
     #
     #     optional_value_fields_required: false
+
+    # The SCIM standard `/Schemas` endpoint lists, by default, all known schema
+    # definitions with the mutabilty (read-write, read-only, write-only) state
+    # described by those definitions, and includes all defined attributes. For
+    # user-defined schema, this will typically exactly match your underlying
+    # mapped attribute and model capability - it wouldn't make sense to define
+    # your own schema that misrepresented the implementation! For core SCIM RFC
+    # schema, though, you might want to only list actually mapped attributes.
+    # Further, if you happen to have a non-compliant implementation especially
+    # in relation to mutability of some attributes, you may want to report that
+    # accurately in the '/Schemas' list, for auto-discovery purposes. To switch
+    # to a significantly slower but more accurate render method for the list,
+    # driven by your resource subclasses and their attribute maps, set:
+    #
+    #     schema_list_from_attribute_mappings: [...array...]
+    #
+    # ...where you provide an Array of *models*, your classes that include the
+    # Scimitar::Resources::Mixin module and, therefore, define an attribute map
+    # translating SCIM schema attributes into actual implemented data. These
+    # must *uniquely* describe, via the Scimitar resources they each declare in
+    # their Scimitar::Resources::Mixin::scim_resource_type implementation, the
+    # set of schemas and extended schemas you want to render. Should resources
+    # share schema, the '/Schemas' endpoint will fail since it cannot determine
+    # which model attribute map it should use and it needs the map in order to
+    # resolve the differences (if any) between what the schema might say, and
+    # what the actual underlying model supports.
+    #
+    # It is further _very_ _strongly_ _recommended_ that, for any
+    # +scim_attributes_map+ containing a collection which has "list:" key (for
+    # an associative array of zero or more entities; the Groups to which a User
+    # might belong is a good example) then you should also specify the "class:"
+    # key, giving the class used for objects in that associated collection. The
+    # class *must* include Scimitar::Resources::Mixin, since its own attribute
+    # map is consulted in order to render the part of the schema describing
+    # those associated properties in the owning resource. If you don't do this,
+    # and if you're using ActiveRecord, then Scimitar attempts association
+    # reflection to determine the collection class - but that's more fragile
+    # than just being told the exact class in the attribute map. No matter how
+    # this class is determined, though, it must be possible to create a simple
+    # instance with +new+ and no parameters, since that's needed in order to
+    # call Scimitar::Resources::Mixin#scim_mutable_attributes.
   })
 
 end