Subject: [scim] attribute selection in query responses

From: Dale Olds <[email-masked]>
Date: Wed, 29 Aug 2012 16:30:07 -0700

I am looking at draft-ietf-scim-api-00, though I think this issue has 
not changed since the 1.0 and 1.1 API specs. Section 3.2.2 shows an 
example query of:

GET /Users?attributes=userName

In the example reply, the results include just the userName attribute of 
all users (since no filter was included). Section 3.7 describes the use 
of the attributes parameter.

> Consumers MAY request a partial Resource representation on any
> operation that returns a Resource within the response by specifying
> the URL query parameter 'attributes'. When specified, each Resource
> returned MUST contain the minimal set of Resource attributes and, MUST
> contain no other attributes or Sub-Attributes than those explicitly
> requested. The query parameter attributes value is a comma separated
> list of Resource attribute names in standard,attribute notation
> <http://www.simplecloud.info/specs/draft-scim-api-00.html#attribute-notation>form
> (e.g. userName, name, emails).

My questions about this section:

1. If an attribute parameter is used to request a partial resource 
representation, does that mean lack of an attributes parameter means the 
full resource representation is returned?

2. If #1 is 'no', can a full representation be requested without knowing 
the attribute names beforehand?

3. the phrase "MUST contain the minimal set of Resource attributes and, 
MUST contain no other attributes or Sub-Attributes than those explicitly 
requested" only applies if the attribute parameter is given. I assume 
the minimal set of attributes is that referred to in section 3.2, but 
does that phrase mean union or intersection of minimal set and requested 
set? If I request attribute=userName, should I get the id and metadata 
back with each resource?

4. If #3 is 'intersection', is there some way to specify that I want the 
requested attribute + whatever the service provider defines as the 
minimal set?

--Dale

---

From: Trey Drake <[email-masked]>
Date: Wed, 29 Aug 2012 20:09:14 -0500

On Aug 29, 2012, at 6:30 PM, Dale Olds <[email-masked]> wrote:

> I am looking at draft-ietf-scim-api-00, though I think this issue has not changed since the 1.0 and 1.1 API specs. Section 3.2.2 shows an example query of:
> 
> In the example reply, the results include just the userName attribute of all users (since no filter was included). Section 3.7 describes the use of the attributes parameter.
> 
> 1. If an attribute parameter is used to request a partial resource representation, does that mean lack of an attributes parameter means the full resource representation is returned?
Yes*.  I add the asterisk as the Service Provider may choose to filter the set of returned attributes.     

> 
> 2. If #1 is 'no', can a full representation be requested without knowing the attribute names beforehand?
N/A
> 
> 3. the phrase "MUST contain the minimal set of Resource attributes and, MUST contain no other attributes or Sub-Attributes than those explicitly requested" only applies if the attribute parameter is given. I assume the minimal set of attributes is that referred to in section 3.2, but does that phrase mean union or intersection of minimal set and requested set? If I request attribute=userName, should I get the id and metadata back with each resource?
> 
Currently, it does specify the Service Provider return the id and meta-data.  We discussed considering meta-data akin to LDAP operational attributes, but we didn't play that thought process out. 

> 4. If #3 is 'intersection', is there some way to specify that I want the requested attribute + whatever the service provider defines as the minimal set?
> 
N/A
> --Dale

Thanks,
Trey
> 
> 
> _______________________________________________
> scim mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/scim

---

From: Dale Olds <[email-masked]>
Date: Wed, 29 Aug 2012 18:34:19 -0700

Thanks, Trey. Does the following updated paragraph give the correct meaning?

Consumers MAY request a partial Resource representation on any operation 
that returns a Resource within the response by specifying the URL query 
parameter 'attributes'. When specified, each Resource returned MUST 
contain the attributes or Sub-Attributes explicitly requested in 
addition to the minimal set of Resource attributes, and no others. The 
query parameter 'attributes' value is a comma separated list of Resource 
attribute names in standard, attribute notation form (e.g. userName, 
name, emails). If no 'attributes' parameter is given, a full Resource 
representation is returned.

--Dale

---

From: Trey Drake <[email-masked]>
Date: Wed, 29 Aug 2012 20:39:59 -0500

Yes.

On Aug 29, 2012, at 8:34 PM, Dale Olds <[email-masked]> wrote:

> Consumers MAY request a partial Resource representation on any operation that returns a Resource within the response by specifying the URL query parameter 'attributes'. When specified, each Resource returned MUST contain the attributes or Sub-Attributes explicitly requested in addition to the minimal set of Resource attributes, and no others. The query parameter 'attributes' value is a comma separated list of Resource attribute names in standard, attribute notation form (e.g. userName, name, emails). If no 'attributes' parameter is given, a full Resource representation is returned.
> 
> --Dale
>

---

From: Dale Olds <[email-masked]>
Date: Thu, 30 Aug 2012 22:53:03 -0700

On more nit on this issue. It would also be useful for the example 
output in section 3.2.2 to reflect the union of minimal and requested 
attributes.

Instead of this:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "totalResults":2,
   "schemas":["urn:scim:schemas:core:1.0"],
   "Resources":[
     {
       "userName":"bjensen"
     },
     {
       "userName":"jsmith"
     }
   ]
}

it should be (if I understand the minimal set of id, meta, and perhaps 
externalId correctly):

HTTP/1.1 200 OK
Content-Type: application/json

{
   "totalResults":2,
   "schemas":["urn:scim:schemas:core:1.0"],
   "Resources":[
     {
       "userName":"bjensen",
       "id":"2819c223-7f76-453a-919d-413861904646",
       "meta":{
            "created":"2011-08-01T18:29:49.793Z",
            "lastModified":"2011-08-01T18:29:49.793Z",
"location":"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646",
            "version":"W\/\"a330bc54f0671c9\""
        }
     {
       "userName":"jsmith"
       "id":"3819c223-7f76-453a-919d-413861904647",
       "meta":{
            "created":"2011-08-01T18:29:49.793Z",
            "lastModified":"2011-08-01T18:29:49.793Z",
"location":"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646",
            "version":"W\/\"a330bc54f0671c9\""
        }
     }
   ]
}

---

From: Eliot Lear <[email-masked]>
Date: Fri, 31 Aug 2012 09:27:45 +0200

Just along these lines, I'd like to strongly suggest to the working
group that we clearly describe the correct way for others to extend the
use of SCIM.  XML is a natural for this with its use of namespaces.  I'm
not sufficiently versed in JSON to say how it should be done that way,
but I'm sure something can be done, right?

Eliot

On 8/31/12 7:53 AM, Dale Olds wrote:
>>> returned MUST contain the attributes or Sub-Attributes explicitly
>>> requested in addition to the minimal set of Resource attributes, and
>>> no others. The query parameter 'attributes' value is a comma
>>> separated list of Resource attribute names in standard, attribute
>>> notation form (e.g. userName, name, emails). If no 'attributes'
>>> parameter is given, a full Resource representation is returned.
>>>
>>> --Dale
>>>
>>>>> I am looking at draft-ietf-scim-api-00, though I think this issue
>>>>> has not changed since the 1.0 and 1.1 API specs. Section 3.2.2
>>>>> shows an example query of:
>>>>>
>>>>> In the example reply, the results include just the userName
>>>>> attribute of all users (since no filter was included). Section 3.7
>>>>> describes the use of the attributes parameter.
>>>>>
>>>>> representation, does that mean lack of an attributes parameter
>>>>> means the full resource representation is returned?
>>>>> 3. the phrase "MUST contain the minimal set of Resource attributes
>>>>> and, MUST contain no other attributes or Sub-Attributes than those
>>>>> explicitly requested" only applies if the attribute parameter is
>>>>> given. I assume the minimal set of attributes is that referred to
>>>>> in section 3.2, but does that phrase mean union or intersection of
>>>>> minimal set and requested set? If I request attribute=userName,
>>>>> should I get the id and metadata back with each resource?
>>>>>
>>>> Currently, it does specify the Service Provider return the id and
>>>> meta-data.  We discussed considering meta-data akin to LDAP
>>>> operational attributes, but we didn't play that thought process out.
>>>>
>>>>> 4. If #3 is 'intersection', is there some way to specify that I
>>>>> want the requested attribute + whatever the service provider
>>>>> defines as the minimal set?
>>>>>
>>>> N/A
>>>>> --Dale
>>>> Thanks,
>>>> Trey

---

From: Kelly Grizzle <[email-masked]>
Date: Fri, 31 Aug 2012 13:20:04 +0000

SCIM does define an extension model, although it could be described more explicitly in the spec.  Section 4 of the core schema draft explains how to extend a schema - http://tools.ietf.org/html/draft-ietf-scim-core-schema-00#section-4.  

You can see an example of how this is done in the enterprise user extension representation - http://tools.ietf.org/html/draft-ietf-scim-core-schema-00#section-11.3.  Note that the schemas attribute has declares use of the enterprise extension.  The actual enterprise attributes are namespaced by the schema URN, like this:

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Eliot Lear
Sent: Friday, August 31, 2012 2:28 AM
To: Dale Olds
Cc: [email-masked]; Trey Drake
Subject: Re: [scim] attribute selection in query responses

Just along these lines, I'd like to strongly suggest to the working group that we clearly describe the correct way for others to extend the use of SCIM.  XML is a natural for this with its use of namespaces.  I'm not sufficiently versed in JSON to say how it should be done that way, but I'm sure something can be done, right?

Eliot

On 8/31/12 7:53 AM, Dale Olds wrote:
>>>>>> operation that returns a Resource within the response by 
>>>>>> specifying the URL query parameter 'attributes'. When specified, 
>>>>>> each Resource returned MUST contain the minimal set of Resource 
>>>>>> attributes and, MUST contain no other attributes or 
>>>>>> Sub-Attributes than those explicitly requested. The query 
>>>>>> parameter attributes value is a comma separated list of Resource 
>>>>>> attribute names in standard,attribute notation

---

From: Kelly Grizzle <[email-masked]>
Date: Fri, 31 Aug 2012 13:21:33 +0000

Sorry for the misfire ... sent to early! ;)

... like this:

  "urn:scim:schemas:extension:enterprise:1.0": {
    "employeeNumber": "701984",
    "costCenter": "4130",
    "organization": "Universal Studios",
    "division": "Theme Park",
    "department": "Tour Operations",
    "manager": {
      "managerId": "26118915-6090-4610-87e4-49d8ca9f808d",
      "displayName": "John Smith"
    }
  }

--Kelly

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Eliot Lear
Sent: Friday, August 31, 2012 2:28 AM
To: Dale Olds
Cc: [email-masked]; Trey Drake
Subject: Re: [scim] attribute selection in query responses

Eliot

---

From: Kelly Grizzle <[email-masked]>
Date: Fri, 31 Aug 2012 17:35:40 +0000

I agree with both the new text and the need for the minimal attributes in the example.  Melinda, could you please add this to the tracker when you get a chance?

--Kelly

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Dale Olds
Sent: Friday, August 31, 2012 12:53 AM
To: Trey Drake
Cc: [email-masked]
Subject: Re: [scim] attribute selection in query responses

On more nit on this issue. It would also be useful for the example output in section 3.2.2 to reflect the union of minimal and requested attributes.

Instead of this:

HTTP/1.1 200 OK

{
   "totalResults":2,

it should be (if I understand the minimal set of id, meta, and perhaps externalId correctly):

HTTP/1.1 200 OK

{
   "totalResults":2,

On 08/29/2012 06:39 PM, Trey Drake wrote:
>>>>> attributes and, MUST contain no other attributes or Sub-Attributes 
>>>>> than those explicitly requested. The query parameter attributes 
>>>>> value is a comma separated list of Resource attribute names in 
>>>>> standard,attribute notation