Subject: [scim] Proposed text for schema resources vs. messages

From: Phil Hunt <[email-masked]>
Date: Fri, 27 Feb 2015 10:17:48 -0800

IMPORTANT:  We need to get this information published next week if we are to make the Dallas meeting deadline. Please respond by Tuesday Mar 3, 8AM Pacific. Based on feedback I will publish a minor revision to schemas doc Tuesday afternoon, and on Thursday revisions to API.

In a previous thread (https://www.ietf.org/mail-archive/web/scim/current/msg02128.html), Erik proposed we use different attributes to distinguish between SCIM messages and resources (msgType and schemas).

I have taken a look at the impact on the documents and I think the solution may be perceived as somewhat more complex than consistently using “schemas”.  The main reason is that someone opening a JSON object now has to look for two different attributes to tell if the object is a SCIM object of any type. I am not sure this matters in practice, but it does “feel” complex from a media type perspective.

From an editorial and IANA perspective, I believe using “msgType” means that we have to build a separate IANA registry for messages distinct from schemas. Given that the review process is essentially the same, I’m not sure there is a lot of benefit. I wonder then if clarifying text might not work as well.

What I have done is written a new introduction to section 3 of the API specification. My hope is that this sets the stage for how SCIM protocol works and clearly establishes the differences between SCIM resources and messages.

Action Item:  PLEASE INDICATE (by next Tuesday morning if possible):

A.  Given the text below, does anyone strongly prefer using “msgType” instead (and creating a new registry for it)?

B.  Comments on the text.

Thanks!

PROPOSED TEXT:
3.  SCIM Protocol

3.1.  Introduction

   SCIM is a protocol based on HTTP [RFC7230].  Along with HTTP headers
   and URIs, SCIM uses JSON [RFC7159] payloads to convey both SCIM
   resources as well as request parameters and response information such
   as errors in the form of JSON based messages.  To identify this
   content, SCIM uses a media type of "application/scim+json" (see
   Section 8.1).

   A SCIM resource is a JSON object that may be created, maintained, and
   retrieved through HTTP methods as described in this document.  Each
   JSON resource representation contains a "schemas" attribute that
   contains a list of one or more URIs that indicate included SCIM
   schemas that may be used to indicate the attributes contained within
   a resource.  When querying a SCIM service provider's "/Schemas"
   endpoint for schema definition (see Section 8.7
   [I-D.ietf-scim-core-schema]), the response describes how a service
   provider supports an attribute including schema meta-attributes such
   as case-exactness, mutability, uniqueness, returnability, and whether
   it is required.  While SCIM schemas and associated extension model is
   defined in [I-D.ietf-scim-core-schema], SCIM clients should expect
   that some attribute schema MAY change from deployment to deployment.
   In cases where SCIM may be used as an open protocol in front of an
   application service, it is quite reasonable to expect that some
   service providers MAY only support a sub-set of the schema defined in
   [I-D.ietf-scim-core-schema].

   A SCIM message is a JSON object that conveys protocol parameters
   about a SCIM request or response that are defined by this
   specification.  As with a SCIM resource, a SCIM message is a JSON
   object that contains a "schemas" attribute with a URI whose namespace
   prefix begins with "urn:ietf:params:scim:api:".  As SCIM protocol
   messages are fixed and defined by SCIM specifications and registered
   extensions, SCIM message schemas using the above prefix URN SHALL NOT
   be discoverable using the "/Schemas" endpoint.

   As SCIM in intended for use within cross-domain environments where
   schemas MAY vary, techniques such as document validation, such as in
   [XML-Schema], are not recommended.  A SCIM service provider
   interprets a request in the context of its own schema (which may be
   different from the client's schema) and the processing rules
   described for each SCIM request.  The following sections in this
   document define processing rules for SCIM that provide allowances for
   differences where appropriate.  For example, in a SCIM PUT request,
   "readOnly" attributes are ignored, while "readWrite" attributes are
   updated.  There is no need for the client to discover which
   attributes are "readOnly" and remove them from the PUT request in
   advance in order to be accepted.  Similarly a SCIM client SHOULD NOT
   expect a service provider to return SCIM resources with exactly the
   same schema and values as submitted.  SCIM responses SHALL reflect
   resource state as interpreted by the SCIM service provider.

3.2.  SCIM Endpoints

   The SCIM protocol specifies well-known endpoints and HTTP methods for
   managing resources defined in the core schema; i.e., "User" and

Phil

@independentid
www.independentid.com
[email-masked]