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

From: Erik Wahlström <[email-masked]>
Date: Tue, 3 Dec 2013 13:18:51 +0000

I created a ticket regarding "Spec defines "Consumer" but uses the word "client" through out the spec.”  http://tools.ietf.org/wg/scim/trac/ticket/53

So, should we call it client instead of Consumer? And Server instead of Service Provider?

I prefer client/server instead of Consumer/Service Provider due to the fact that we use it all through the code, it feels a bit forced to use Consumer. And it also conflicts a bit with SAML Service Provider.

Any thoughts?

/ Erik

On 02 Oct 2013, at 09:46, Erik Wahlström <[email-masked]<mailto:[email-masked]>> wrote:

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

---

From: Michael Hammer <[email-masked]>
Date: Tue, 3 Dec 2013 14:16:59 +0000

If we are talking about a protocol and not some vague business process, I
agree.

Mike

From: scim [mailto:[email-masked]] On Behalf Of Erik Wahlström
Sent: Tuesday, December 03, 2013 8:19 AM
To: <[email-masked]>
Subject: Re: [scim] Some comments after a review of the 02 specs

I created a ticket regarding "Spec defines "Consumer" but uses the word
"client" through out the spec.”
http://tools.ietf.org/wg/scim/trac/ticket/53

So, should we call it client instead of Consumer? And Server instead of
Service Provider? 

I prefer client/server instead of Consumer/Service Provider due to the fact
that we use it all through the code, it feels a bit forced to use Consumer.
And it also conflicts a bit with SAML Service Provider.

Any thoughts?

/ Erik

On 02 Oct 2013, at 09:46, Erik Wahlström <[email-masked]>
wrote:

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, 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:

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

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:

--   

From:
  Service Provider views of the new Resource.  When a Resource is created,
its

--

From:

--

From:

To:   

--

From:

To:

-- 

From:

-- 

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:

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

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

---

From: Phil Hunt <[email-masked]>
Date: Tue, 3 Dec 2013 09:31:33 -0800

Agreed.  The word "consumer" can be ambiguous.  Eg.  a Client is sending updates to a service provider vs a client retrieving resources from the service provider.  Which is the consumer depends on the action too much.

Phil

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

On 2013-12-03, at 6:16 AM, Michael Hammer <[email-masked]> wrote:

> If we are talking about a protocol and not some vague business process, I agree.
>  
> Mike
>  
>  
> On 02 Oct 2013, at 09:46, Erik Wahlström <[email-masked]> wrote:
> 
> 
> _______________________________________________
> scim mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/scim