Subject: [scim] PUT and meaning of omitting values

From: Phil Hunt <[email-masked]>
Date: Fri, 16 May 2014 12:16:37 -0700

I was just thinking about our PUT rules and was considering what it means to omit values.  Passwords (writeOnly attributes) came to mind as problematic in the current text.

Old text:
readWrite, writeOnly  Any values provided SHALL replace the existing
      attribute values.  Omitting the attribute or specific values means
      the attribute or specific value SHALL be removed;

I would like to propose this text instead:
readWrite, writeOnly  Any values provided SHALL replace the existing
      attribute values. For readWrite attributes, omitting the attribute 
      or specific values means the attribute or specific value SHALL 
      be removed;

I am not sure if we need to put in text for “writeOnly” attributes. For passwords you would expect the client to omit password and you would not expect the existing password value to be removed (unlike readWrite).  However because writeOnly could be attributes other than passwords (user security questions), I’m reluctant to specify what should be done.

Thoughts?

If your head is exploding now, don’t worry, mine is.

Phil

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

---

From: Bill Mills <[email-masked]>
Date: Fri, 16 May 2014 14:21:57 -0700 (PDT)

PUT is a replacement of the entire object, use it carefully....

The stuff you do not get to change like the metadata is interesting.  PUT shouldn't overwrite the creation time of the object for example.  Metatdata is where it gets hard, the actual contents are easy.

On Friday, May 16, 2014 12:36 PM, Phil Hunt <[email-masked]> wrote:

Old text:
readWrite, writeOnly  Any values provided SHALL replace the existing attribute values.  Omitting the attribute or specific values means the attribute or specific value SHALL be removed;

I would like to propose this text instead:
readWrite, writeOnly  Any values provided SHALL replace the existing attribute values. For readWrite attributes, omitting the attribute 
or specific values means the attribute or specific value SHALL 
be removed;

Thoughts?

Phil

@independentid
[email-masked]

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

---

From: "Morteza Ansari (moransar)" <[email-masked]>
Date: Sat, 17 May 2014 00:09:37 +0000

There are other cases to consider here. If the reader does not have read access to some attributes, those attributes should not be removed either.  Essentially in our implementation PUT is a special case of PATCH to handle authorization case and metadata (much like operational attributes were handled in LDAP).

Cheers,
Morteza

From: Bill Mills <[email-masked]<mailto:[email-masked]>>
Reply-To: Bill Mills <[email-masked]<mailto:[email-masked]>>
Date: Friday, May 16, 2014 at 2:21 PM
To: Phil Hunt <[email-masked]<mailto:[email-masked]>>, "[email-masked]<mailto:[email-masked]>" <[email-masked]<mailto:[email-masked]>>
Subject: Re: [scim] PUT and meaning of omitting values

On Friday, May 16, 2014 12:36 PM, Phil Hunt <[email-masked]<mailto:[email-masked]>> wrote:
I was just thinking about our PUT rules and was considering what it means to omit values.  Passwords (writeOnly attributes) came to mind as problematic in the current text.

Old text:

      be removed;

Thoughts?

Phil

@independentid
www.independentid.com<http://www.independentid.com/>
[email-masked]<mailto:[email-masked]>

_______________________________________________
scim mailing list
[email-masked]<mailto:[email-masked]>
https://www.ietf.org/mailman/listinfo/scim

---

From: Bill Mills <[email-masked]>
Date: Fri, 16 May 2014 17:14:11 -0700 (PDT)

I would argue that if you don't have all of the data for a user then using PUT is wrong and you must use PATCH.

On Friday, May 16, 2014 5:09 PM, Morteza Ansari (moransar) <[email-masked]> wrote:

Cheers,
Morteza 

From: Bill Mills <[email-masked]>
Reply-To: Bill Mills <[email-masked]>
Date: Friday, May 16, 2014 at 2:21 PM
To: Phil Hunt <[email-masked]>, "[email-masked]" <[email-masked]>
Subject: Re: [scim] PUT and meaning of omitting values

Old text:

Thoughts?

Phil

@independentid

---

From: Phil Hunt <[email-masked]>
Date: Fri, 16 May 2014 17:29:34 -0700

We had that discussion just today in our internal standards group. Access control impacts what a client can see. At the very least omission processing should only count for attributes a client can see. 

I know that’s complex, but I can’t see it working otherwise.

I think the power of PUT over PATCH is that for doc centric SPs, PUT is easier (maybe).  The other advantage (or disadvantage) is that the client code is simplified leaving the SP to figure out what the implied patch is.  

But I think the big use case for PUT will be bean based clients. Consider java beans where you have a bean holding state in memory (e.g. for a UI). Depending on your architecture you may not know how the bean has been modified compared to the original. For default bean approaches, you just want to save the bean which probably translates into a PUT.  I should probably ask our Jersey experts about this.

As for Bills comment, that was the same sentiment we had internally. Try not to use it. Ugh.

Phil

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

---

From: "Morteza Ansari (moransar)" <[email-masked]>
Date: Sat, 17 May 2014 00:53:01 +0000

I agree, I don’t think there is a choice here if the implementation has fine grained access control.  The question is how to describe this in the spec!

From: Phil Hunt <[email-masked]<mailto:[email-masked]>>
Date: Friday, May 16, 2014 at 5:29 PM
To: Morteza Ansari <[email-masked]<mailto:[email-masked]>>
Cc: Bill Mills <[email-masked]<mailto:[email-masked]>>, "[email-masked]<mailto:[email-masked]>" <[email-masked]<mailto:[email-masked]>>
Subject: Re: [scim] PUT and meaning of omitting values

Phil

@independentid
www.independentid.com<http://www.independentid.com>
[email-masked]<mailto:[email-masked]>

On May 16, 2014, at 5:09 PM, Morteza Ansari (moransar) <[email-masked]<mailto:[email-masked]>> wrote:

Cheers,
Morteza

Old text:

      be removed;

Thoughts?

Phil

@independentid

---

From: "Morteza Ansari (moransar)" <[email-masked]>
Date: Sat, 17 May 2014 00:54:04 +0000

But the client doesn’t know it doesn’t have all the data.  From the client perspective it has the whole object.

From: Bill Mills <[email-masked]<mailto:[email-masked]>>
Reply-To: Bill Mills <[email-masked]<mailto:[email-masked]>>
Date: Friday, May 16, 2014 at 5:14 PM
To: Morteza Ansari <[email-masked]<mailto:[email-masked]>>, Phil Hunt <[email-masked]<mailto:[email-masked]>>, "[email-masked]<mailto:[email-masked]>" <[email-masked]<mailto:[email-masked]>>
Subject: Re: [scim] PUT and meaning of omitting values

On Friday, May 16, 2014 5:09 PM, Morteza Ansari (moransar) <[email-masked]<mailto:[email-masked]>> wrote:
There are other cases to consider here. If the reader does not have read access to some attributes, those attributes should not be removed either.  Essentially in our implementation PUT is a special case of PATCH to handle authorization case and metadata (much like operational attributes were handled in LDAP).

Cheers,
Morteza

Old text:

      be removed;

Thoughts?

Phil

@independentid

---

From: Phil Hunt <[email-masked]>
Date: Fri, 16 May 2014 18:07:48 -0700

I think implicit delete (absence of a value) is problematic because it means the SCIM API has to know about the access control system.  This is probably not a good idea. 

What about an explicit methodology like this:

Consider example JSON record: 
{
  “attr_A”:”First”,
  “attr_B”:”Second”,
  “attr_C”:”Third”,
  “attr_D”:”Four"
}

Apply a PUT of:
{
  “attr_B”:null,
  “attr_C”:””,
  “attr_D”:{}
}

Results in:
{
  “attr_A”:”First”,
  “attr_B”:null,
  “attr_C”:””,
}

In the above you can see that only attr_D is removed.  attr_A is untouched.  attr_B and C are set to empty string and null respectively (which means null and empty string are valid values).

According to RFC7158, an empty object is valid per the ABNF:
object = begin-object [ member *( value-separator member ) ]
               end-object

The empty object notation also makes sense for complex attributes since it signals the entire complex attribute is removed.

Phil

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

On May 16, 2014, at 5:54 PM, Morteza Ansari (moransar) <[email-masked]> wrote:

> To: Morteza Ansari <[email-masked]>, Phil Hunt <[email-masked]>, "[email-masked]" <[email-masked]>

---

From: Bill Mills <[email-masked]>
Date: Fri, 16 May 2014 21:30:00 -0700 (PDT)

The client *should* know the schema, so it can know whether it can use PUT or not.  If the server has schema elements hidden from the client, then it's the server's problem to solve.

What you've got here is PUT except when it's not PUT it' PATCH, and PATCH.  That's not OK.

On Friday, May 16, 2014 5:54 PM, Morteza Ansari (moransar) <[email-masked]> wrote:

Cheers,
Morteza 

Old text:

Thoughts?

Phil

@independentid

---

From: Phil Hunt <[email-masked]>
Date: Tue, 20 May 2014 12:00:50 -0700

Thinking about this some more, there are many reasons why an attribute may be missing:
A. There is no current value - server should ignore
-OR-
B. There is no value - an implied delete as the client intended the new record to replace the old. 
C. The client can't get or set the attribute due to access control
D. The client was built on an older version of the schema and doesn’t know about it
E. The client never requested the value on GET.

There is a problem here that there is a dramatic difference between a true document-centric API where replacing an HTML file or a JPG is what is intended.

In SCIM, we have an attribute-centric API where individual attributes have different metadata (mutability, required) associated. To assume that a PUT is a simple swap and that missing attribute implies delete is dangerous due to the above (A thru E).

So where normally a client might only send:
{
  “attr_A”:”First”,
  “attr_B”:”Second”,
}
Which leaves the server to wonder:  What about “attr_C” and “attr_D”?

In the new model. The above transaction would leave “attr_C” and attr_D” untouched.

If the client’s intent is to actually remove or wipe out those attributes, they could simply specify all attributes they want to set (for example, use null): 
{
  “attr_A”:”First”,
  “attr_B”:”Second”,
  “attr_C”:null,
  “attr_D”:null
}

From a Java platform perspective, this seems more bean friendly since you are telling the beans to just serialize all values regardless of whether a value has been set. No complex logic required for remembering what was modified, etc. I can’t comment on the .Net stuff. But I can only guess there are parallel issues.

Here is some proposed new text (revised text in bold/blue):
   PUT performs a full update.  Clients MAY retrieve the entire resource
   in advance, add the desired modifications and use HTTP PUT which will
   overwrite all previously stored data.  Since the PUT request performs
   a full update, clients MAY send attributes of the retrieved resource
   and the service provider MUST process according to attribute
   mutability as follows:

   readWrite, writeOnly  Any values provided SHALL replace the existing
      attribute values. For multi-valued attributes, all values SHALL
      be replaced.

   immutable  If values are provided for elements already set in the
      attribute they MUST match existing data or an error is returned.
      If the service provider has no existing values, a new value(s) MAY
      be specified; and,

   readOnly  Any values provided (e.g.  meta.resourceType) SHALL be
      ignored.

   If an attribute is "required", the client MUST specify the attribute
   in the PUT request.

   If a client would like to remove all values of an attribute, the client
   MAY set the attribute to the value “null”. In setting values to “null”
   the client MUST conform to the above mutability rules.

   If an attribute is unspecified by the client, the server SHOULD leave
   any existing values for the attribute unchanged.

   If a value provided for an immutable attribute with an existing value
   is NOT matched, the server SHALL respond with an HTTP response code
   of 400 and an appropriate human readable message indicating an
   attempt to change an immutable attribute.
  ...

IMPORTANT:  The text above does significantly change the meaning of attribute omission and thus is *breaking*.

Phil

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

---

From: Erik Wahlström <[email-masked]>
Date: Wed, 21 May 2014 12:13:20 +0000

Hi,

+1 får the change. But I think we should define exactly what unspecified means in "If an attribute is unspecified by the client”. Is it not in the JSON object at all, is it empty string?

/ Erik

On 20 May 2014, at 21:00, Phil Hunt <[email-masked]<mailto:[email-masked]>> wrote:

      be replaced.

  ...

Phil

@independentid

On May 16, 2014, at 9:30 PM, Bill Mills <[email-masked]<mailto:[email-masked]>> wrote:

On Friday, May 16, 2014 5:54 PM, Morteza Ansari (moransar) <[email-masked]<mailto:[email-masked]>> wrote:
But the client doesn’t know it doesn’t have all the data.  From the client perspective it has the whole object.

Cheers,
Morteza

Old text:

      be removed;

Thoughts?

Phil

@independentid

---

From: Phil Hunt <[email-masked]>
Date: Wed, 21 May 2014 06:59:21 -0700

Ok. 

Phil

> On May 21, 2014, at 5:13, Erik Wahlström <[email-masked]> wrote:
> 
> Hi,
> 
>> On 20 May 2014, at 21:00, Phil Hunt <[email-masked]> wrote:
>>

---

From: Bill Mills <[email-masked]>
Date: Wed, 21 May 2014 09:00:11 -0700 (PDT)

I think you're redefining PATCH and two of the same thing is not good. 

If the client knows the schema and didn't fetch all the data the client must use PATCH. 

If we're solving for a schema mismatch then the client needs to provide a reference to the schema it is using. 

PUT  that accepts a schema reference would solve the problem of the server having to guess the client state. 

Bill

Sent from Yahoo Mail on Android

---

From: Phil Hunt <[email-masked]>
Date: Wed, 21 May 2014 09:22:49 -0700

Right. I agree it starts to duplicate patch. I think this happens with any api that is not document centric. 

But as i said there are many reasons for omission of an attribute we can't account for as service providers. This I would prefer omission have no meaning. 

We could allow the server to optionally interpret null as remove. What we are saying is, if you want to swap the whole resource, you must specify the whole resource. 

I think this is simplest logic overall, it is still idempotent, and is flexible in what we accept. 

A client that doesn't know about null is not affected. 

The only issue is if null is important as a valid attribute value. 

I would recommend dropping PUT but we have use cases for it. 

Phil

> On May 21, 2014, at 9:00, Bill Mills <[email-masked]> wrote:
> 
> 
> From: Phil Hunt <[email-masked]>; 
> To: Bill Mills <[email-masked]>; 
> Cc: Scim WG <[email-masked]>; Morteza Ansari <[email-masked]>; 
> Sent: Tue, May 20, 2014 7:00:50 PM 
>

---

From: Phil Hunt <[email-masked]>
Date: Thu, 22 May 2014 09:53:08 -0700

BTW.  Given that some of our discussion on PUT is pulling back a bit on its value, I notice the language in the current draft says PUT is mandatory and PATCH is optional.
> Resources can be modified in whole or in part via PUT or PATCH,
>    respectively.  Implementers MUST support PUT as specified in
>    Section 9.6 [RFC2616] . Resources such as Groups may be very large
>    hence implementers SHOULD support PATCH [RFC5789] to enable partial
>    resource modifications.

I’m thinking that maybe both should be mandatory (assuming we even keep PUT). I think if we are focused on simplicity for the client, we should recognize that different programming patterns will make clients tend to choose either PUT or PATCH - meaning every server SHOULD support both.

For example, we have the hint from the text that PATCH is really the only way to deal with large groups.
And for bean based programming, PUT is much easier to implement.

Assuming we figure out PUT, does this make sense?

Phil

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

---

From: Bill Mills <[email-masked]>
Date: Thu, 22 May 2014 14:15:31 -0700 (PDT)

Any time.  Want me to call you after I clear my mailbox?  Just getting a chance now.

Old text:

Thoughts?

Phil

@independentid

---

From: Erik Wahlström <[email-masked]>
Date: Fri, 23 May 2014 11:32:38 +0000

The original reasoning for having PUT as mandatory and PATCH as optional was that it should be as easy as possible. And I could potentially just do a GET of a resource, change a value and then do a PUT and everything and it will be updated. PATCH was just a more detailed and fancy thing to do when you only want to do minor changes (like adding a user to a group). As a rule, I think we should make it easier to create a service provider. In a “using corporate identity in the cloud”- scenario, the client’s can be bundled into IAM software but it’s all the SAML service providers and such out there that would implement user management using SCIM. That means that there will be a lot of service providers, and one client build into some enterprise software. Client’s can discover if PATCH is supported using the service provider config. So, I would like to keep both :) and using PUT for a simple replace, and PATCH when it’s needed (optional).
/ Erik

On 22 May 2014, at 18:53, Phil Hunt <[email-masked]<mailto:[email-masked]>> wrote:

Resources can be modified in whole or in part via PUT or PATCH,
   respectively.  Implementers MUST support PUT as specified in
   Section 9.6 [RFC2616]<http://tools.ietf.org/html/rfc2616#section-9.6> . Resources such as Groups may be very large
   hence implementers SHOULD support PATCH [RFC5789<http://tools.ietf.org/html/rfc5789>] to enable partial
   resource modifications.

Phil

@independentid

On May 21, 2014, at 9:00 AM, Bill Mills <[email-masked]<mailto:[email-masked]>> wrote:

Bill

Sent from Yahoo Mail on Android<https://overview.mail.yahoo.com/mobile/?.src=Android>

________________________________
From: Phil Hunt <[email-masked]<mailto:[email-masked]>>;
To: Bill Mills <[email-masked]<mailto:[email-masked]>>;
Cc: Scim WG <[email-masked]<mailto:[email-masked]>>; Morteza Ansari <[email-masked]<mailto:[email-masked]>>;
Subject: Re: [scim] PUT and meaning of omitting values
Sent: Tue, May 20, 2014 7:00:50 PM

      be replaced.

   any existing values for the attribute
 unchanged.

  ...

Phil

@independentid
www.independentid.com<http://www.independentid.com/>
[email-masked]<javascript:return>

On May 16, 2014, at 9:30 PM, Bill Mills <[email-masked]<javascript:return>> wrote:

On Friday, May 16, 2014 5:54 PM, Morteza Ansari (moransar) <[email-masked]<javascript:return>> wrote:
But the client doesn’t know it doesn’t have all the data.  From the client perspective it has the whole object.

From: Bill Mills <[email-masked]<javascript:return>>
Reply-To: Bill Mills <[email-masked]<javascript:return>>
Date: Friday, May 16, 2014 at 5:14 PM
To: Morteza Ansari <[email-masked]<javascript:return>>, Phil Hunt <[email-masked]<javascript:return>>, "[email-masked]<javascript:return>" <[email-masked]<javascript:return>>
Subject: Re: [scim] PUT and meaning of omitting values

On Friday, May 16, 2014 5:09 PM, Morteza Ansari (moransar) <[email-masked]<javascript:return>> wrote:
There are other cases to consider here. If the reader does not have read access to some attributes, those attributes should not be removed either.  Essentially in our implementation PUT is a special case of PATCH to handle authorization case and metadata (much like operational attributes were handled in LDAP).

Cheers,
Morteza

From: Bill Mills <[email-masked]<javascript:return>>
Reply-To: Bill Mills <[email-masked]<javascript:return>>
Date: Friday, May 16, 2014 at 2:21 PM
To: Phil Hunt <[email-masked]<javascript:return>>, "[email-masked]<javascript:return>" <[email-masked]<javascript:return>>
Subject: Re: [scim] PUT and meaning of omitting values

On Friday, May 16, 2014 12:36 PM, Phil Hunt <[email-masked]<javascript:return>> wrote:
I was just thinking about our PUT rules and was considering what it means to omit values.  Passwords (writeOnly attributes) came to mind as problematic in the current text.

Old text:

      be removed;

Thoughts?

Phil

@independentid
www.independentid.com<http://www.independentid.com/>
[email-masked]<javascript:return>

_______________________________________________
scim mailing list
[email-masked]<javascript:return>
https://www.ietf.org/mailman/listinfo/scim

_______________________________________________
scim mailing list
[email-masked]<javascript:return>
https://www.ietf.org/mailman/listinfo/scim

---

From: Kelly Grizzle <[email-masked]>
Date: Fri, 23 May 2014 13:06:10 +0000

I agree with Erik.  This was the original desire for having both PUT and PATCH, and I believe that it is still valid.

Here is a simple solution - when a client does a PUT the server compares the request body with what would have been returned by a GET to the client.  Anything that is missing in the request body but would not have been returned in a GET is ignored.

This will handle the access control issues (option C that you listed below).  IMHO SCIM doesn't need to try to support E (client requested a partial resource).  Option D (client was built with a different version of the schema) may be something that SCIM should try to handle, but could be mitigated through the PATCH operation.  Or, as Bill suggested, the client could inform the server about the schema that it is using.  That seems like overkill to me, though.

--Kelly

From: scim [mailto:[email-masked]] On Behalf Of Erik Wahlström
Sent: Friday, May 23, 2014 6:33 AM
To: Phil Hunt
Cc: Scim WG
Subject: Re: [scim] Optionality of PUT/PATCH (was Re: PUT and meaning of omitting values)

The original reasoning for having PUT as mandatory and PATCH as optional was that it should be as easy as possible. And I could potentially just do a GET of a resource, change a value and then do a PUT and everything and it will be updated. PATCH was just a more detailed and fancy thing to do when you only want to do minor changes (like adding a user to a group). As a rule, I think we should make it easier to create a service provider. In a "using corporate identity in the cloud"- scenario, the client's can be bundled into IAM software but it's all the SAML service providers and such out there that would implement user management using SCIM. That means that there will be a lot of service providers, and one client build into some enterprise software. Client's can discover if PATCH is supported using the service provider config. So, I would like to keep both :) and using PUT for a simple replace, and PATCH when it's needed (optional).
/ Erik

   resource modifications.

I'm thinking that maybe both should be mandatory (assuming we even keep PUT). I think if we are focused on simplicity for the client, we should recognize that different programming patterns will make clients tend to choose either PUT or PATCH - meaning every server SHOULD support both.

Phil

@independentid

Bill

D. The client was built on an older version of the schema and doesn't know about it

So where normally a client might only send:
{
  "attr_A":"First",
  "attr_B":"Second",
}
Which leaves the server to wonder:  What about "attr_C" and "attr_D"?

In the new model. The above transaction would leave "attr_C" and attr_D" untouched.

If the client's intent is to actually remove or wipe out those attributes, they could simply specify all attributes they want to set (for example, use null):
{
  "attr_A":"First",
  "attr_B":"Second",
  "attr_C":null,
  "attr_D":null
}

>From a Java platform perspective, this seems more bean friendly since you are telling the beans to just serialize all values regardless of whether a value has been set. No complex logic required for remembering what was modified, etc. I can't comment on the .Net stuff. But I can only guess there are parallel issues.

   mutability as follows:

      be replaced.

      be specified; and,

      ignored.

   in the PUT request.

   MAY set the attribute to the value "null". In setting values to "null"

 unchanged.

  ...

Phil

@independentid

What you've got here is PUT except when it's not PUT it' PATCH, and PATCH.  That's not OK.
On Friday, May 16, 2014 5:54 PM, Morteza Ansari (moransar) <[email-masked]<javascript:return>> wrote:
But the client doesn't know it doesn't have all the data.  From the client perspective it has the whole object.

Cheers,
Morteza

Old text:

      be removed;

I am not sure if we need to put in text for "writeOnly" attributes. For passwords you would expect the client to omit password and you would not expect the existing password value to be removed (unlike readWrite).  However because writeOnly could be attributes other than passwords (user security questions), I'm reluctant to specify what should be done.

Thoughts?

If your head is exploding now, don't worry, mine is.

Phil

@independentid

---

From: Phil Hunt <[email-masked]>
Date: Fri, 23 May 2014 11:08:19 -0700

I agree, PUT should be easy, but determining client “intent” is not easy.  Easy often translates in to complex for one side or the other.  :-)

To refresh everyone...

We have two problems to address:

A.  For service providers, whether each of PUT and PATCH are MTI.  Keep in mind that if only PUT is mandatory, clients will tend to implement only that. For multi-value objects like groups, PUT is harder than PATCH. Should PATCH than be MTI?

B.  In identity protocols (LDAP, DSML, SCIM, SAML) we tend to specify those attributes which have values rather then specifying every attribute in the schema. This keeps protocols efficient. However, it leaves mystery as to whether a missing attribute means no value or can’t see the value. This makes attribute value deletion complex. If a missing value is “unspecified”, does it mean delete or does it mean nothing at all?  
  —this makes PUT very complex because server behaviour is not clear.

Bill and I had a chat on the phone yesterday and we came up with some for B:

1.  Leave SCIM as is. But have the server have more flexibility on determining meaning. A server MAY interpret attribute omission as remove attribute. This seems very complex because the client is unclear as to how servers will react and may result in many different client connectors accounting for differences.

2.  Specify all attributes: Client specifies all values it wants to set including those with no values. 
a. Omission of an attribute has no meaning and leaves attribute unmodified. 
b. A client may use []-no values, or null to imply a multi-value or single-valued object is to have its values removed.  

For client code, when serializing an object into application/scim+json, the code would output *all* attributes whether they have values or not.  This makes PUT very “wordy” but clear on intent. If a client is a UI for user self-service, a “bean" client does not have to worry about tracking which attributes are modified.  The client’s persistence system just does a “save” invoking PUT as below. 

A request would look like follows:

   PUT /Users/2819c223-7f76-453a-919d-413861904646
   Host: example.com
   Accept: application/json
   Content-Type: application/json
   Authorization: Bearer h480djs93hd8
   If-Match: W/"a330bc54f0671c9"

   {
     "schemas":["urn:scim:schemas:core:2.0:User"],
     "id":"2819c223-7f76-453a-919d-413861904646",
     "userName":"bjensen",
     "externalId”:[],
     "name":{
       "formatted":"Ms. Barbara J Jensen III",
       "familyName":"Jensen",
       "givenName":"Barbara",
       "middleName”:none
     },
     “addresses”:[],
     "emails":[
       {
           "value":"[email-masked]"
       },
       {
           "value":"[email-masked]"
       }
     ]
   }

In the above example, externalId, addresses, and name.middleName are removed.

3. Use “attributes” parameter: Allow clients to specify the attributes they are replacing using the attributes attribute (much like it would have done on get). In this case omission means remove the value:

   PUT /Users/2819c223-7f76-453a-919d-413861904646
   Host: example.com
   Accept: application/json
   Content-Type: application/json
   Authorization: Bearer h480djs93hd8
   If-Match: W/"a330bc54f0671c9"

   {
     “meta”:{
       “attributes”:[“schemas”,“id”,”userName”,”externalId”,”name”,”addresses”,”emails”]
     }
     "schemas":["urn:scim:schemas:core:2.0:User"],
     "id":"2819c223-7f76-453a-919d-413861904646",
     "userName":"bjensen",
     "name":{
       "formatted":"Ms. Barbara J Jensen III",
       "familyName":"Jensen",
       "givenName":"Barbara",
     },
     "emails":[
       {
           "value":"[email-masked]"
       },
       {
           "value":"[email-masked]"
       }
     ]
   }

This JSON would have the same effect as case 2 above (removing externalId, name.middleName,and addresses).

4. Schema-based: Use a specify by resourceType or schema. When a clients specifies a resourceType (e.g. User) or a schema, it indicates it is replacing all attributes of that resourceType or Schema.

This one is closer to the RESTful mantra of document swap. However I worry that access control may be finer grained than the schema. For example, the server may have access control rules that prevents a client from modifying or retrieving the entire “User” schema. If true, we are back to scenario 1 above where server has to decide intent — did the client intend to remove attr x or is it that the client cannot access attr x?

Phil

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

On May 23, 2014, at 6:06 AM, Kelly Grizzle <[email-masked]> wrote:

> Here is a simple solution – when a client does a PUT the server compares the request body with what would have been returned by a GET to the client.  Anything that is missing in the request body but would not have been returned in a GET is ignored.
>  
> This will handle the access control issues (option C that you listed below).  IMHO SCIM doesn’t need to try to support E (client requested a partial resource).  Option D (client was built with a different version of the schema) may be something that SCIM should try to handle, but could be mitigated through the PATCH operation.  Or, as Bill suggested, the client could inform the server about the schema that it is using.  That seems like overkill to me, though.
>  
> --Kelly
>  
> On 22 May 2014, at 18:53, Phil Hunt <[email-masked]> wrote:
> 
>