Subject: [scim] Detailed error and status codes

From: Phil Hunt <[email-masked]>
Date: Tue, 24 Jun 2014 12:01:42 -0700

With regards to tickets 37, 46, 67, it looks like we will have some normative changes required.  I am also expecting new SCIM error codes as we look at the possible reasons a server might return Bad Request or other HTTP status codes.

Currently, the example response from PATCH, we use “error” to indicate a detailed error. 

 "error":"mutability"

From Response Codes Section, no detail error is defined:
HTTP/1.1 404 NOT FOUND

{
  "schemas": ["urn:scim:api:messages:2.0:Error"],
  "Errors":[
    {
      "description":"Resource 2819c223-7f76-453a-919d-413861904646 not found",
      "code":"404"
    }
  ]
}

Doing a search around Twitter, AWS, and many others, I see that “code” is often used to indicate a detailed error message (“mutability”) and status is used to indicate HTTP status.  

In an attempt to bring consistency across the API document, I am proposing we use http_status and scim_code. This will help make clear what we are referring to and allow existing implementations to co-exist for a while (by having different names).

Are there any objections to normalizing the spec around following format and attributes?

Proposed example:

HTTP/1.1 400 Bad Request
   Content-Type: application/scim+json;charset=UTF-8
   Cache-Control: no-store
   Pragma: no-cache

   {
     "schemas": ["urn:scim:api:messages:2.0:Error"],
     "Errors":[
       {
         “scim_code":"mutability”,
         “http_status”:400,
         "error_description":"Attribute 'id' is readOnly."
       },
        . . .
     ]
   }

Phil

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

---

From: Julian Reschke <[email-masked]>
Date: Tue, 24 Jun 2014 21:23:13 +0200

On 2014-06-24 21:01, Phil Hunt wrote:
> With regards to tickets 37, 46, 67, it looks like we will have some
> normative changes required.  I am also expecting new SCIM error codes as
> we look at the possible reasons a server might return Bad Request or
> other HTTP status codes.
>
> * "error":"mutability"*
> *HTTP/1.1 404 NOT FOUND*
>        *"description":"Resource 2819c223-7f76-453a-919d-413861904646 not found",
>        "code":"404"*
>      }
>    ]
> }
>
>
> Doing a search around Twitter, AWS, and many others, I see that “code”
> is often used to indicate a detailed error message (“mutability”) and
> status is used to indicate HTTP status.
>
> In an attempt to bring consistency across the API document, I am
> proposing we use http_status and scim_code. This will help make clear
> what we are referring to and allow existing implementations to co-exist
> for a while (by having different names).
>
> _Are there any objections to normalizing the spec around following
> format and attributes?_
>
> Proposed example:
>
> *HTTP/1.1 400 Bad Request*
>
>           *“scim_code":"mutability”,*
>
> *          “http_status”:400,*
> ...

You may want to read 
<http://tools.ietf.org/html/draft-nottingham-http-problem-06>...

Best regards, Julian

---

From: Erik Wahlström <[email-masked]>
Date: Tue, 24 Jun 2014 19:25:00 +0000

Hi Phil,

Prefer camel case though, not personally, but just to keep it according to rest of spec :) Hence scimCode, httpStatus, errorDescription instead.

I’m still not fully on board of having multiple error codes in one response. I think it was mostly a typo in 1.0 specs to be frank :) All scim implementations I’ve seen just display one error code at the time.

By the way, I liked the fact that you made http status an int instead of string.

/ Erik

On 24 Jun 2014, at 21:01, Phil Hunt <[email-masked]<mailto:[email-masked]>> wrote:

 "error":"mutability"

HTTP/1.1 404 NOT FOUND

{

Proposed example:

HTTP/1.1 400 Bad Request

   {

         “http_status”:400,

        . . .

     ]

}

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: Phil Hunt <[email-masked]>
Date: Tue, 24 Jun 2014 16:30:31 -0700

Note: July 04 is the LAST day for us to potentially submit updates for the IETF90 meeting.  This gives us about 1.5 weeks to close off the error issues and update the drafts.  If you have a moment please take a look and comment as soon as possible...

Julian thanks for the suggestion.  For the rest of the group’s benefit, the draft Julian referenced suggests the following attributes be returned in a standardized detailed error JSON body…

>    A problem details object MAY have the following members:
> 
>    o  "type" (string) - An absolute URI [RFC3986] that identifies the
>       problem type.  When dereferenced, it SHOULD provide human-readable
>       documentation for the problem type (e.g., using HTML
>       [W3C.REC-html401-19991224]).  When this member is not present, its
>       value is assumed to be "about:blank".
>    o  "title" (string) - A short, human-readable summary of the problem
>       type.  It SHOULD NOT change from occurrence to occurrence of the
>       problem, except for purposes of localisation.
>    o  "status" (number) - The HTTP status code ([RFC2616], Section 6)
>       generated by the origin server for this occurrence of the problem.
>    o  "detail" (string) - An human readable explanation specific to this
>       occurrence of the problem.
>    o  "instance" (string) - An absolute URI that identifies the specific
>       occurrence of the problem.  It may or may not yield further
>       information if dereferenced.

Here is the corresponding example error response:
>    HTTP/1.1 403 Forbidden
>    Content-Type: application/problem+json
>    Content-Language: en
> 
>    {
>     "type": "http://example.com/probs/out-of-credit",
>     "title": "You do not have enough credit.",
>     "detail": "Your current balance is 30, but that costs 50.",
>     "instance": "http://example.net/account/12345/msgs/abc",
>     "balance": 30,
>     "accounts": ["http://example.net/account/12345",
>                  "http://example.net/account/67890"]
>    }

Julian, what is the value of having “type” be a URI?  Why not just have a SCIM specific attribute (scimType) and use simple keywords? (asking mainly for the WG’s benefit). I guess the strong case is that by standardizing HTTP responses, client code gets simplified. However, using standard attributes creates the namespace conflict issue.  So we need URI based error codes.

The SCIM specs could adopt the “type”, “detail”, and “status”. We would register a namespace of urn:scim:error:apil:2.0 in the SCIM IANA section in addition to api:messages, schema:core, etc.  This would give detail error types of:
  urn:scim:error:api:2.0:mutability, urnscim:error:api:2.0:filter, etc.

The other items, like title, instance, etc could be optional or just omitted from SCIM spec. —> we would just indicate that clients should expect attributes within the JSON message other than those defined by the SCIM drafts.

IMPORTANT NOTE:  the format suggested by Julian allows for only one error at a time.  Erik had commented he prefers to return only one. I tend to agree. In the case of BULK requests, this is not really an issue since each BULK operation gets its own response block.

In the interests of time, any objections to using type (with URI based error codes), detail, status, per above and limiting to ONE per response? 

I know these are normative changes….however I’m pretty sure we can’t avoid changes in the final document clean up whether or not we adopt the proposed standardized error response.

Cheers,

Phil

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

On Jun 24, 2014, at 12:23 PM, Julian Reschke <[email-masked]> wrote:

> You may want to read <http://tools.ietf.org/html/draft-nottingham-http-problem-06>...
> 
> Best regards, Julian
> 
> [email-masked]

---

From: Erik Wahlström <[email-masked]>
Date: Wed, 25 Jun 2014 07:25:19 +0000

So that would make it look like the following right?

{
  "schemas": ["urn:scim:api:messages:2.0:Error"],
  "Error":
    {
      "type": "urn:scim:api:error:2.0:mutability",
      "title": “Attribute is readOnly.",
      "detail": “Attribute 'id' is readOnly and can’t be changed in a PATCH request.",
      “status": 400
    }
}

I replaced Errors with Error.
Also replaced urn:scim:error:api:2.0:mutability with urn:scim:api:error:2.0:mutability

That works for me.
/ Erik

On 25 Jun 2014, at 01:30, Phil Hunt <[email-masked]<mailto:[email-masked]>> wrote:

   o  "type" (string) - An absolute URI [RFC3986<http://tools.ietf.org/html/rfc3986>] that identifies the
      [W3C.REC-html401-19991224<http://tools.ietf.org/html/draft-nottingham-http-problem-06#ref-W3C.REC-html401-19991224>]).  When this member is not present, its
   o  "status" (number) - The HTTP status code ([RFC2616], Section 6<http://tools.ietf.org/html/rfc2616#section-6>)

   HTTP/1.1 403 Forbidden

   {

Cheers,

Phil

@independentid

On Jun 24, 2014, at 12:23 PM, Julian Reschke <[email-masked]<mailto:[email-masked]>> wrote:

Currently, the example response from PATCH, we use “error” to indicate a
detailed error.

* "error":"mutability"*

*HTTP/1.1 404 NOT FOUND*

{

Proposed example:

   {

*          “http_status”:400,*

        . . .

     ]

   }
...

Best regards, Julian

---

From: Phil Hunt <[email-masked]>
Date: Wed, 25 Jun 2014 08:05:08 -0700

Yes. :-)

Phil

> On Jun 25, 2014, at 0:25, Erik Wahlström <[email-masked]> wrote:
> 
>> On 25 Jun 2014, at 01:30, Phil Hunt <[email-masked]> wrote:
>>

---

From: Phil Hunt <[email-masked]>
Date: Wed, 25 Jun 2014 12:07:11 -0700

On the call today (Erik, Bjorn, Morteza, and myself), we discussed the error issue.

The major concern with the draft suggested by Julian is really one of timing - we would prefer not to hold SCIM up. A good middle-ground approach is to align with the draft, but define the error fully within SCIM (using the SCIM mime type and schema namespace).

The proposal on the call is to SCIM mime/type of application/scim+json in error responses and include the SCIM error message schema declaration.  

{
 “schema”: "urn:scim:api:messages:2.0:Error” (indicates the SCIM message type)
 "scimType" - a keyword indicating the detail error (e.g.  “mutability”)
 "status" - the HTTP status (should correspond to the response header)
 "detail" - a detailed, human-readable message
}

Servers MAY return additional attributes (e.g. ones from http-problem draft).  The only mandatory attributes are “schema” and “status”.  For example on anonymous self-registration scenarios, servers may be unwilling to give detail error responses for security reasons.

The reason for using scimType (instead of type) is to avoid any confusion with “type” from draft-nottingham-http-problem and its eventual use of “type”.

In a future update to SCIM we can then transition to align with the HTTP Problem draft by simply adding “type” in the way it defines. 

Phil

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

---

From: David Möbius <[email-masked]>
Date: Thu, 26 Jun 2014 11:09:50 +0200

Hello,

I would like to adjust to add a "error group" type to the error object.

Example:

{
  “schema”: "urn:scim:api:messages:2.0:Error”
  "scimGroupType" - "saving user"
  "scimDetailType" - "username allready taken"
  "status" - the HTTP status (should correspond to the response header)
  "detail" - "The username 'marissa' is already taken"
 }

The scimGroupType and the scimDetailType should never change if you do
the same mistage to make it machine readable.

Example and Reason:
I have a mask where the user can create an account. I have created my
html page the way that the user can't do "anything" wrong. The only
think the could do wrong is to use a existing username.

After I send the new user to the backend I get an exception. Since I
wan't to display the exception message in german or an other language I
need to know what type of exception was the problem.

I would like to give the User kind of messages:

1. The user used a given username: If this is the problem I can see it
with the help of the scimDetailType which will always be "username
already taken".

2. It is somethink wrong with the userdata (for example a email without
@ which I forget to check in my frontend). That something is wrong with
the userdata in generall I can see with the "scimGroupType"

3. Something else happens and I want to log the exception in my logs and
give an general message to the user

In my front end it could look like

if(scimException.getScimDetailType.equals("username allready taken")){

errorMessage = "in german: Your username is already taken. Plase use a
other one."
}else if(scimException.getScimGroupType.equals("saving user")){

errorMessage = "in german: Could not save your data. Please check your
given data.";
}else{

log.Error(scimException);
errorMessage= "in german: an error happen. Please try again later."
}

For this reason it would be good if we have 2 error codings in our error
json object. What do you think about this?

by David

Am 25.06.2014 21:07, schrieb Phil Hunt:
> The major concern with the draft suggested by Julian is really one of
> timing - we would prefer not to hold SCIM up. A good middle-ground
> approach is to align with the draft, but define the error fully within
> SCIM (using the SCIM mime type and schema namespace).
> 
> The proposal on the call is to SCIM mime/type of application/scim+json
> in error responses and include the SCIM error message schema declaration.  
> 
> {
> Servers MAY return additional attributes (e.g. ones from http-problem
> draft).  The only mandatory attributes are “schema” and “status”.  For
> example on anonymous self-registration scenarios, servers may be
> unwilling to give detail error responses for security reasons.
> 
> The reason for using scimType (instead of type) is to avoid any
> confusion with “type” from draft-nottingham-http-problem and its
> eventual use of “type”.
> 
> In a future update to SCIM we can then transition to align with the HTTP
> Problem draft by simply adding “type” in the way it defines. 
> 
> Phil
> 
> @independentid
> www.independentid.com <http://www.independentid.com>
> [email-masked] <mailto:[email-masked]>
> 
> 
> 
> On Jun 25, 2014, at 12:25 AM, Erik Wahlström
> <[email-masked] <mailto:[email-masked]>>
> wrote:
> 
>>> Note: July 04 is the LAST day for us to potentially submit updates
>>> for the IETF90 meeting.  This gives us about 1.5 weeks to close off
>>> the error issues and update the drafts.  If you have a moment please
>>> take a look and comment as soon as possible...
>>>
>>> Julian thanks for the suggestion.  For the rest of the group’s
>>> benefit, the draft Julian referenced suggests the following
>>> attributes be returned in a standardized detailed error JSON body…
>>>
>>>>    o  "type" (string) - An absolute URI [RFC3986 <http://tools.ietf.org/html/rfc3986>] that identifies the
>>>>       [W3C.REC-html401-19991224 <http://tools.ietf.org/html/draft-nottingham-http-problem-06#ref-W3C.REC-html401-19991224>]).  When this member is not present, its
>>>>    o  "status" (number) - The HTTP status code ([RFC2616], Section 6 <http://tools.ietf.org/html/rfc2616#section-6>)
>>> Julian, what is the value of having “type” be a URI?  Why not just
>>> have a SCIM specific attribute (scimType) and use simple keywords?
>>> (asking mainly for the WG’s benefit). I guess the strong case is that
>>> by standardizing HTTP responses, client code gets simplified.
>>> However, using standard attributes creates the namespace conflict
>>> issue.  So we need URI based error codes.
>>>
>>> The SCIM specs could adopt the “type”, “detail”, and “status”. We
>>> would register a namespace of urn:scim:error:apil:2.0 in the SCIM
>>> IANA section in addition to api:messages, schema:core, etc.  This
>>> would give detail error types of:
>>> The other items, like title, instance, etc could be optional or just
>>> omitted from SCIM spec. —> we would just indicate that clients should
>>> expect attributes within the JSON message other than those defined by
>>> the SCIM drafts.
>>>
>>> IMPORTANT NOTE:  the format suggested by Julian allows for only one
>>> error at a time.  Erik had commented he prefers to return only one. I
>>> tend to agree. In the case of BULK requests, this is not really an
>>> issue since each BULK operation gets its own response block.
>>>
>>> *_In the interests of time, any objections to using type (with URI
>>> based error codes), detail, status, per above and limiting to ONE per
>>> response?  _*
>>>
>>> I know these are normative changes….however I’m pretty sure we can’t
>>> avoid changes in the final document clean up whether or not we adopt
>>> the proposed standardized error response.
>>>
>>> Cheers,
>>>
>>> Phil
>>>
>>> @independentid
>>> www.independentid.com <http://www.independentid.com/>
>>> [email-masked] <mailto:[email-masked]>
>>>
>>>
>>>
>>>> [email-masked] <mailto:[email-masked]>
>>> [email-masked] <mailto:[email-masked]>

---

From: Phil Hunt <[email-masked]>
Date: Thu, 26 Jun 2014 08:34:50 -0700

1. scimType is intended to indicate many of these details. Like a unique index conflict (e.g. “uniqueness”).  That said, I’m not sure it would indicate which attribute caused the failure.  Should we indicate which attribute is not unique or which attribute has a mutability error through another response element?

2. Why isn’t the standard accept-langauge headers not appropriate to localize the detail message? 

There are also some security considerations here in cross-domain scenarios. It is very likely that even if we mandate detail errors that many SPs will return generic Status 400 errors to non-privledged clients.

Phil

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

---

From: David Möbius <[email-masked]>
Date: Fri, 27 Jun 2014 10:32:31 +0200

scimType is good, I just think that another type would be great. The
names themself are not important for me.

I think to generate a Exception message in the needed language would not
be a part of the server. Every client should create their own exception
messages. This way it is easy to translate my homepage to an other
language. The scim server should only create exception messages in one
standard language which would be english.

---

From: Phil Hunt <[email-masked]>
Date: Fri, 27 Jun 2014 11:35:58 -0700

David,

The problem with going to more specific error code granularity is that most of these codes would seem to fall outside the protocol and schema specs themselves and depend very much on the context of the application being built using SCIM or upon the provisioning system that backs the SCIM API.

I think I am clear on why you need them. I am less clear on why every service provider should support an enhanced level of signalling or even if it is possible they can.

Can you provide a list of this error code detail you would like to see?

Any other thoughts here?

Phil

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