Handle resource attributes mutability and returnability

[azmeuk]

use cases

In several situations described in RFC7644, partial objects payloads can be generated:

• §3.3: Resource creation POST requests may not have the id or meta attributes.
• §3.4.2: Responses of GET requests where the attributes and excludedAttributes parameters are used.
• §3.4.3: Responses of search POST requests where the attributes and excludedAttributes parameters are used.
• §3.5.1: Resource replacement PUT requests may not have the id or meta attributes.
• §3.9: Responses of GET requests where the attributes and excludedAttributes parameters are used.
• §3.14: Resource creation POST requests may not have the id or meta attributes.

There are actually two situations:

• Partial responses when client asked for a subset of the object attributes, using attributes or excludedAttributes in their requests.
• Client creation or replacement requests without the id and meta parameters.

documentation elements

RFC7643 §3.1 indicates that the id, externalId and meta parameters must be defined for all the resources (except for ServiceProviderConfig and ResourceType). But be defined is different than mandatory:

   [...] these attributes MUST be defined for all resources,
   including any extended resource types.  When accepted by a service
   provider (e.g., after a SCIM create), the attributes "id" and "meta"
   (and its associated sub-attributes) MUST be assigned values by the
   service provider.  Common attributes are considered to be part of
   every base resource schema and do not use their own "schemas" URI.

RFC7643 §3.1 indicates that the id is mandatory for each representation, but also that it is forbidden on client creation requests.

id
    Each representation of the resource MUST include a
    non-empty "id" value. 
    [...] The value of
    the "id" attribute is always issued by the service provider and
    MUST NOT be specified by the client. [...]

RFC7643 §3.1 indicates that the meta parameter is not relevant for client requests:

   meta
      A complex attribute containing resource metadata.  All "meta"
      sub-attributes are assigned by the service provider (have a
      "mutability" of "readOnly"), and all of these sub-attributes have
      a "returned" characteristic of "default".  This attribute SHALL be
      ignored when provided by clients.  "meta" contains the following
      sub-attributes:

conclusion

For a given resource, it is expected to have different fields wether it is part of a client request or a server response. The behavior for server response is dictated by Schema.returned and the behavior for client requests is dictated by Schema.mutability.

• Server responses payloads can have any subset of the resource attributes, but will always include attributes which returned value is marked as always (like id) and never include attributes which returned value is never (such as password)
• Client POST creation request payloads must have the mandatory fields, except those with readOnly mutability such as id which are forbidden.
• Client replacement PUT payloads can have any readWrite or writeOnly mutability attribute, and readOnly such as id which are ignored, but immutable attributes are forbidden.

possible solutions

• Maybe partial models can be achieved with https://github.com/team23/pydantic-partial.
• Maybe a solution can be found with annotations to enforce the immutability and returned characteristics:

  class User:
  id: Annotated[Optional[str], Returned.always, Mutability.immutable] = None
  ...

  And then implement custom validate_payload and dump_payload methods which takes mutability and returned parameters:

# Client validating a server response
user = User.validate_payload(payload, returned=(Returned.always, Returned.default, Returned.request))

# Server validating a client POST request
user = User.validate_payload(payload, mutability=(Mutability.read_write, Mutability.immutable, Mutability.write_only))

# Server validating a client PUT request
user = User.validate_put_request(payload, mutability=(Mutability.read_write, Mutability.read_only, Mutability.write_only))

# Server generating a response
payload = user.dump_payload(user, returned=(Returned.always, Returned.default, Returned.request))

# Client building a POST payload
payload = user.dump_payload(user, mutability=(Mutability.read_write, Mutability.immutable, Mutability.write_only))

# Client building a PUT payload
payload = user.dump_payload(user, mutability=(Mutability.read_write, Mutability.read_only, Mutability.write_only))