Subject: [scim] Proposed new text for PUT (ticket 76)

From: Phil Hunt <[email-masked]>
Date: Mon, 2 Jun 2014 13:03:51 -0700

Here is some proposed new text.  I’ve tried to tweak the text a bit to help solve Ticket 76 regarding what to do about missing or omitted attributes.

After some analysis, I think this is closest in logic to how people are using PUT now.  Because PUT is mandatory, I believe we need to be very precise.

I have also added text stating that PUT should not be used to create new resources. Is the word “SHOULD” appropriate?  The real problem with using PUT for resource creation is the client gets to create their own identifier.

> 3.3.1.  Modifying with PUT
> 
>    HTTP PUT is used to perform a full update of a resource's attributes.
>    Clients having previously retrieved the entire resource in advance,
>    update the desired attributes and use HTTP PUT to replace previously
>    stored attributes.  HTTP PUT SHOULD NOT be used to create a new
>    resource.
> 
>    As the operation intent is to replace attributes, SCIM clients MAY
>    send all attributes regardless of each attribute's mutability.  The
>    server will apply attribute by attribute replace according to the
>    following attribute mutability rules:
> 
>    readWrite, writeOnly  Any values provided SHALL replace the existing
>       attribute values.
> 
>    immutable  If values are already set in the attribute they MUST match
>       existing data or an error is returned.  If the service provider
>       has no existing values, the new value(s) SHALL be applied.
> 
>    readOnly  Any values provided (e.g.  meta.resourceType) SHALL be
>       ignored.
> 
>    If an attribute is "required", clients MUST specify the attribute in
>    the PUT request.
> 
>    Clients MAY specify "null" or empty set "[]" to clear an existing
>    value or clear a multi-valued array.
> 
>    Since a client may not have access to, or may not be aware of, the
>    full schema for a resource, omitted or unspecified values SHOULD be
>    ignored.
> 
>    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.  [[Editor: An appropriate
>    error code should be indicated e.g. 'mutability']]
> 
>    Unless otherwise specified a successful PUT operation returns a 200
>    OK response code and the entire resource within the response body,
>    enabling the client to correlate the client's and Provider's views of
>    the updated resource.  Example:
> 

Phil

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

---

From: Leif Johansson <[email-masked]>
Date: Wed, 11 Jun 2014 20:38:19 +0200

On 2014-06-02 22:03, Phil Hunt wrote:
> Here is some proposed new text.  I’ve tried to tweak the text a bit to
> help solve Ticket 76 regarding what to do about missing or omitted
> attributes.
> 

I want to encourage/urge everyone to think about and review this
proposal. It is very likely the last big issue left to us!

> After some analysis, I think this is closest in logic to how people are
> using PUT now.  Because PUT is mandatory, I believe we need to be very
> precise.
> 
> I have also added text stating that PUT should not be used to create new
> resources. Is the word “SHOULD” appropriate?  The real problem with
> using PUT for resource creation is the client gets to create their own
> identifier.
> 
> www.independentid.com <http://www.independentid.com>
> [email-masked] <mailto:[email-masked]>
> 
> 
> 
> 
> 
> _______________________________________________
> scim mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/scim
>

---

From: Thomas Krille <[email-masked]>
Date: Wed, 18 Jun 2014 14:51:42 +0200

Hello,

looks good to me. +1 for not creating new resources via PUT.

i will have to try to implement the revised behavior in order to issue a
final, more qualified statement.

Best Regards

Thomas Krille
Softwareentwicklung
tarent solutions GmbH

Telefon +49 (0) 30 138803-128
Telefax +49 (0) 228 54881-235
[email-masked]

Rochusstraße 2-4, D-53123 Bonn • http://www.tarent.de/
Tel: +49 228 54881-0 • Fax: +49 228 54881-235
HRB AG Bonn 5168 • USt-ID (VAT): DE122264941
Geschäftsführer: Dr. Stefan Barth, Kai Ebenrett, Boris Esser, Alexander
Steeg

---

From: Phil Hunt <[email-masked]>
Date: Wed, 18 Jun 2014 11:44:01 -0700

Another complication is “default” values.

A client omitting an attribute:
* may not know about the attribute as being part of the representation (e.g. because of access control)
* may intend to replace the values of the attribute with nothing (null).
* may be simply saying assign the default value.

Having a client being able to say “attribute”:null would be a nice way to allow clients to differentiate between,  don’t know/want default and explicitly intend to replace with a null value.  e.g. set roles to null.

Do we want to put this in the next draft and give it a try? We can always pull it out in the following draft if implementers find it doesn’t make the logic simpler.  I do caution that we are hoping to go to last call in Toronto.  

Phil

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

On Jun 18, 2014, at 5:51 AM, Thomas Krille <[email-masked]> wrote:

> i will have to try to implement the revised behavior in order to issue a final, more qualified statement.
> 
> Best Regards
> 
> Thomas Krille
> Softwareentwicklung
> tarent solutions GmbH
> 
> Geschäftsführer: Dr. Stefan Barth, Kai Ebenrett, Boris Esser, Alexander Steeg
> 
>

---

From: Phil Hunt <[email-masked]>
Date: Thu, 19 Jun 2014 11:04:00 -0700

Group,

Please find below, some new text for PUT. This should keep most of our current logic intact but I hope addresses the issues giving clients and servers the right balance of “intent” and “interpretation”.

As I mentioned in my previous issue, there is the issue of unspecified values being defaulted by the server.In the example below, I show the client setting “roles” to [] in order to say the User is to have no roles (as opposed to a default set).  If you like this, I will apply similar language to the POST operation.

See bold sections below...
3.3.1.  Replacing with PUT

   HTTP PUT is used to perform a full update of a resource's attributes.
   Clients that MAY have previously retrieved the entire resource in
   advance and revised it, MAY replace the resource using an HTTP PUT.
   Because SCIM resource identifiers are typically assigned by the
   service provider, HTTP PUT SHOULD NOT be used to create new
   resources.

   As the operation intent is to replace all attributes, SCIM clients
   MAY send all attributes regardless of each attribute's mutability.
   The server will apply attribute by attribute replace according to the
   following attribute mutability rules:

   immutable  If value(s) are already set for the attribute, the input
      value(s) MUST match or HTTP status 400 SHOULD be returned with
      error code "mutability".  If the service provider has no existing
      values, the new value(s) SHALL be applied.

   Attributes whose mutability is "readWrite", that are omitted from the
   request body, MAY be assumed to be not asserted by the client.  The
   service provider MAY assume any existing values are to be cleared or
   the service provider MAY assign a default value to the final resource
   representation.  Service providers MAY take into account whether a
   client has access to, or understands, all of the resource's
   attributes when deciding whether non-asserted attributes SHALL be
   removed or defaulted.  Clients that would like to override a server
   defaults, MAY specify "null" for a single-valued attribute or an
   empty array "[]" for a multi-valued attribute to clear all values.

   PUT /Users/2819c223-7f76-453a-919d-413861904646
   Host: example.com
   Accept: application/scim+json
   Content-Type: application/scim+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":"bjensen",
     "name":{
       "formatted":"Ms. Barbara J Jensen III",
       "familyName":"Jensen",
       "givenName":"Barbara",
       "middleName":"Jane"
     },
     "roles":[],
     "emails":[
       {
           "value":"[email-masked]"
       },
       {
           "value":"[email-masked]"
       }
     ]
   }

Phil

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

---

From: Kelly Grizzle <[email-masked]>
Date: Fri, 20 Jun 2014 19:21:47 +0000

+1.  I like this, Phil.  Good work!

From: scim [mailto:[email-masked]] On Behalf Of Phil Hunt
Sent: Thursday, June 19, 2014 1:04 PM
To: Thomas Krille
Cc: Leif Johansson; [email-masked]
Subject: Re: [scim] Proposed new text for PUT (ticket 76)

Group,

Please find below, some new text for PUT. This should keep most of our current logic intact but I hope addresses the issues giving clients and servers the right balance of "intent" and "interpretation".

As I mentioned in my previous issue, there is the issue of unspecified values being defaulted by the server.In the example below, I show the client setting "roles" to [] in order to say the User is to have no roles (as opposed to a default set).  If you like this, I will apply similar language to the POST operation.

   resources.

      attribute values.

      ignored.

   the PUT request.

   Host: example.com<http://example.com>

   {

     "userName":"bjensen",

     "externalId":"bjensen",

     "name":{

       "familyName":"Jensen",

       "givenName":"Barbara",

       "middleName":"Jane"

     },

     "roles":[],

     "emails":[

       {

           "value":"[email-masked]<mailto:[email-masked]>"

       },

       {

           "value":"[email-masked]<mailto:[email-masked]>"

       }

     ]

   }

Phil

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

On Jun 18, 2014, at 11:44 AM, Phil Hunt <[email-masked]<mailto:[email-masked]>> wrote:

Another complication is "default" values.

Having a client being able to say "attribute":null would be a nice way to allow clients to differentiate between,  don't know/want default and explicitly intend to replace with a null value.  e.g. set roles to null.

Do we want to put this in the next draft and give it a try? We can always pull it out in the following draft if implementers find it doesn't make the logic simpler.  I do caution that we are hoping to go to last call in Toronto.

Phil

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

On Jun 18, 2014, at 5:51 AM, Thomas Krille <[email-masked]<mailto:[email-masked]>> wrote:

Hello,

Best Regards

Thomas Krille
Softwareentwicklung
tarent solutions GmbH

Telefon +49 (0) 30 138803-128
Telefax +49 (0) 228 54881-235
[email-masked]<mailto:[email-masked]>

Rochusstraße 2-4, D-53123 Bonn * http://www.tarent.de/
Tel: +49 228 54881-0 * Fax: +49 228 54881-235
HRB AG Bonn 5168 * USt-ID (VAT): DE122264941
Geschäftsführer: Dr. Stefan Barth, Kai Ebenrett, Boris Esser, Alexander Steeg

2014-06-11 20:38 GMT+02:00 Leif Johansson <[email-masked]<mailto:[email-masked]>>:
On 2014-06-02 22:03, Phil Hunt wrote:
> Here is some proposed new text.  I've tried to tweak the text a bit to

> resources. Is the word "SHOULD" appropriate?  The real problem with
> www.independentid.com<http://www.independentid.com/> <http://www.independentid.com<http://www.independentid.com/>>
> [email-masked]<mailto:[email-masked]> <mailto:[email-masked]<mailto:[email-masked]>>
>
>
>
>
>
> [email-masked]<mailto:[email-masked]>

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

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

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

---

From: Thomas Krille <[email-masked]>
Date: Mon, 23 Jun 2014 10:17:12 +0200

+1, thank you Phil

Thomas Krille
Softwareentwicklung
tarent solutions GmbH

2014-06-20 21:21 GMT+02:00 Kelly Grizzle <[email-masked]>:

> *From:* scim [mailto:[email-masked]] *On Behalf Of *Phil Hunt
> *Sent:* Thursday, June 19, 2014 1:04 PM
> *To:* Thomas Krille
> *Cc:* Leif Johansson; [email-masked]
> *Subject:* Re: [scim] Proposed new text for PUT (ticket 76)
>
>
>
> Group,
>
>
>
> Please find below, some new text for PUT. This should keep most of our
> current logic intact but I hope addresses the issues giving clients and
> servers the right balance of “intent” and “interpretation”.
>
>
>
> As I mentioned in my previous issue, there is the issue of unspecified
> values being defaulted by the server.In the example below, I show the
> client setting “roles” to [] in order to say the User is to have no roles
> (as opposed to a default set).  If you like this, I will apply similar
> language to the POST operation.
>
>
>
> See *bold* sections below...
>
>    *HTTP PUT is used to perform a full update of a resource's attributes.*
>
> *   Clients that MAY have previously retrieved the entire resource in*
>
> *   advance and revised it, MAY replace the resource using an HTTP PUT.*
>
> *   Because SCIM resource identifiers are typically assigned by the*
>
> *   service provider, HTTP PUT SHOULD NOT be used to create new*
>
> *   resources.*
>
>
>
>   * Attributes whose mutability is "readWrite", that are omitted from the*
>
> *   request body, MAY be assumed to be not asserted by the client.  The*
>
> *   service provider MAY assume any existing values are to be cleared or*
>
> *   the service provider MAY assign a default value to the final resource*
>
> *   representation.  Service providers MAY take into account whether a*
>
> *   client has access to, or understands, all of the resource's*
>
> *   attributes when deciding whether non-asserted attributes SHALL be*
>
> *   removed or defaulted.  Clients that would like to override a server*
>
> *   defaults, MAY specify "null" for a single-valued attribute or an*
>
> *   empty array "[]" for a multi-valued attribute to clear all values.*
>
>
>
>      *"roles":[],*
> Having a client being able to say “attribute”:null would be a nice way to
> allow clients to differentiate between,  don’t know/want default and
> explicitly intend to replace with a null value.  e.g. set roles to null.
>
>
>
> Do we want to put this in the next draft and give it a try? We can always
> pull it out in the following draft if implementers find it doesn’t make the
> logic simpler.  I do caution that we are hoping to go to last call in
> Toronto.
>
>
>
> Phil
>
>
>
> @independentid
>
> www.independentid.com
>
> [email-masked]
>
>
>
>
>
>
>