Subject: [scim] Some comments after a review of the 02 specs

From: Erik Wahlström <[email-masked]>
Date: Wed, 2 Oct 2013 07:46:16 +0000

After a review of the -02 specs I found a couple of issues that I guess we need to discuss. I propose adding them all as new issues in the issue tracker of no one objects.

----------------------

In general I think we should add a couple of more examples in our definitions when we talk about example Resources. We always mention User and Group. That's fine but when we start talking about ServiceProviderConifig and ResourceType they come as a surprise and you wonder if they are treated as any Resource or not.

Example:

   Resource:  The Service Provider managed artifact containing one or
      more attributes; e.g., User or Group

   Resource:  The Service Provider managed artifact containing one or
      more attributes; e.g., User, Group, ServiceProviderConfig or ResourceType.

----------------------

In the API documentation we never mension the new URIs like urn:scim:schemas:core:2.0:ListResponse, SearchRequest, Error, BulkRequest, BulkResponse. We also mention urn:scim:schemas:core:2.0:name.givenName and that's real attributes defined in the core schema for a specific User. 

----------------------
In the "3.8 Attribute Notation" section shouln't we also define the core resource type like User and Group when we refrence name.givenName.

Instead of:
 urn:scim:schemas:core:2.0:name.givenName
Have:
 urn:scim:schemas:core:2.0:User:name.givenName

----------------------

We have some language confusion on a lot of places in the specification. In our defintions we define that there exists Consumers and Service Providers. But most of the specification talks about clients and servers. I personally use client and server when I talk about SCIM. Here is a list of where we say client instead of Consumer. The server equivalent is longer.

From:
   "It is RECOMMENDED that
   clients be implemented in such a way that new authentication schemes
   can be deployed.  Implementers SHOULD support existing authentication"
To:
   "It is RECOMMENDED that
   Service Providers and Consumers is implemented in such a way that new authentication schemes
   can be deployed.  Implementers SHOULD support existing authentication"

--   

From:
   "To create new Resources, clients send POST requests to the Resource
   endpoint; i.e., /Users or /Groups."
   
To:
   "To create new Resources, Consumers send POST requests to the Resource
   endpoint; i.e., /Users or /Groups."

--   

From:
   "Since the server is free to
   alter and/or ignore POSTed content, returning the full representation
   can be useful to the client, enabling it to correlate the client and
   server views of the new Resource.  When a Resource is created, its
   URI must be returned in the response Location header."
To:
   "Since the server is free to
   alter and/or ignore POSTed content, returning the full representation
   can be useful to the Consumer, enabling it to correlate the Consumer and
   Service Provider views of the new Resource.  When a Resource is created, its
   URI must be returned in the response Location header."

--

From:
   "Below, the client sends a POST request containing a User"
To:
   "Below, the Consumer sends a POST request containing a User."
   
--

From:
   "To retrieve a known Resource, clients send GET requests to the
   Resource endpoint; e.g., /Users/{id} or /Groups/{id}."

To:   
   "To retrieve a known Resource, Consumers send GET requests to the
   Resource endpoint; e.g., /Users/{id} or /Groups/{id}."

--

From:
   "Clients MAY execute queries without passing parameters on the URL by
   using the HTTP POST verb combined with the '/.search' path extension."

To:
   "Consumers MAY execute queries without passing parameters on the URL by
   using the HTTP POST verb combined with the '/.search' path extension."

-- 

From:
   "To create a new search result set, a SCIM client sends an HTTP POST
   request to the desired SCIM resource endpoint (ending in '/.search')."
To:
   "To create a new search result set, a SCIM Consumer sends an HTTP POST
   request to the desired SCIM resource endpoint (ending in '/.search')."

-- 

From:
   "In addition to returning a
   HTTP response code implementers MUST return the errors in the body of
   the response in the client requested format containing the error
   response and, per the HTTP specification, human-readable
   explanations."
To:
   "In addition to returning a
   HTTP response code implementers MUST return the errors in the body of
   the response containing the error response and, per the HTTP specification, human-readable
   explanations."

--

From:
   "In recognition that some clients, servers and firewalls prevent PUT,
   PATCH and DELETE operations a client MAY override the POST operation
   by specifying the custom header "X-HTTP-Method-Override" with the
   desired PUT, PATCH, DELETE operation."
To:
   "In recognition that some clients, servers and firewalls prevent PUT,
   PATCH and DELETE operations a Consumer MAY override the POST operation
   by specifying the custom header "X-HTTP-Method-Override" with the
   desired PUT, PATCH, DELETE operation."

----------------------

And finaly I agree with Steves earlier comment on the mail list, at least the first two suggestions :), regarding section 3.1.5 not beeing up to date. Steve stated:

"Section 3.1.5. (Headed: DateTime) of the SCIM v2 Schema refers to section 3.2.7 which no longer exists and to the (XML Schema Datatypes Specification) which is no longer supported.  I'd suggest we refer to the relevant standards in this paragraph and link to RFC3339 - section 5.6 (http://tools.ietf.org/html/rfc3339#section-5.6), ISO-8601 (http://www.iso.org/iso/catalogue_detail?csnumber=40874) and if humor is tolerated, to Randall Munroe's opinion (https://xkcd.com/1179/)."

/ Erik