Subject: [scim] API comments 3.2 to 3.5

From: Kelly Grizzle <[email-masked]>
Date: Tue, 22 Jul 2014 17:35:19 +0000

More comments... still cranking through the API doc.

> 3.2.2     "Resources":[
>           {
>              "userName":"bjensen"
>           },

This example should include "id" and "meta" since they are always returned (actually ... the example Schema in the schema doc doesn't say whether meta is always returned ... is it?)

> 3.2.2.2    filter=addresses[state eq "CA" and rooms[type eq "bedroom" and
>            number gt 2]]

Should rooms be fully-qualified since it is in an extension (eg - urn:example:schemas:hotel:User)?

> 3.2.2.3   attribute type; i.e., for caee insensitive attributes, sort the

Typo on "caee".

> 3.2.2.3   The following table describes the query response pagination
>           attributes specified by the service provider.

Should "specified" be "returned" here?

> 3.2.2.3   | itemsPerPage | Non-negative Integer. Specifies the number of      |
>           |              | search results returned in a query response page;  |
>           |              | e.g., 10.                                          |

Can the server choose to return an itemsPerPage that differs from the "count" that the client requested.  For example, if the client requests 1000 results, but the server only supports returning 100 at a time, could the server return "itemsPerPage": 100?  We should probably explicitly call out whether this is allowed or not.

> 3.2.2.5  The following attributes control which attributes SHALL be returned
>          with a returned resource.

Recommend changing this to:

     The following URL parameters control which attributes SHALL be returned
     with a returned resource.

> 3.2.3   "Resources":[ ...

This example should include the "id" attribute in the response since it is always returned.

> 3.3.1  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.

Should "defaults" be "default" here?

> 3.3.2.1  o  If the target location does not exist, the attribute and value is
>             added.
>          ...
>          o  If the target location specifies an attribute that does not exist
>             (has no value), the attribute is added with the new value.

It's not clear to me what the difference is between these two.

> 3.3.2.1 The value MAY be a quoted value OR it may be
>         a JSON object containing the sub-attributes of the complex attribute
>         specified in the operation's "path".

This seems like it would just accept strings for simple attributes.  Instead of "quoted value", maybe this should just say "simple value".

> 3.2.2.2   If the target location is a complex-multi-valued attribute and a

Change this to "complex multi-valued" to be consistent with the rest of the spec.  The same term is used multiple times in this section.

> 3.2.2.2    o  If the target location is a complex-multi-valued attribute and a
>               complex filter is specified based on the attribute's sub-
>               attributes, the matching records are removed.

Is "matching records" referring to the "matching complex element"?  I don't know if "matching complex element" is the right term, but we might want to tighten up the language here.  In the examples below this is referred to as "Removal of a value from a complex-multi-valued attribute".  Same comment for section 3.3.2.3.

> 3.2.2.2    Remove all members of a group:
>            ...
>            { "schemas": ["urn:scim:api:messages:2.0:PatchOp"],
>              "op":"remove","path":"members"}

Formatting.  Add newlines to format the JSON:

    {
      "schemas": ["urn:scim:api:messages:2.0:PatchOp"],
      "op":"remove",
      "path":"members"
    }

Another question on the patch syntax.  Some examples just have a single PatchOp in curly braces and some have an array of PatchOps.  Are both syntaxes supported?  Also, should the "schemas" attribute on a PatchOp be on the top-level object, rather than inside each PatchOp element?  For example:

 {
    "schemas": ["urn:scim:api:messages:2.0:PatchRequest"],
    "Operations": [
      {
        "op": "remove",
        "path": "members"
      }
    ]
  }

This example would be closer to the syntax for bulk requests.  This would be my preference to keep single patches and multi-patches consistent.

> 3.2.2.2    The following example shows how to replace all the members of a group
>            with a different members list.
>            [
>              { "schemas": ["urn:scim:api:messages:2.0:PatchOp"],
>                "op":"remove","path":"members"},

Formatting.

> 3.3.2.3   o  If the target location is a complex-multi-valued attribute with a
>              complex filter and a specific sub-attribute (e.g.  "addresses[type
>              eq "work"].streetAddress" ), the matching sub-attribute of the
>              matching record is replaced.

Should "record" be "records" (or whatever terminology we land on) since the path could match multiple values of the multi-valued attribute?

> 3.3.2.3    The following example shows how to change a User's address.  Since
>            address does not have a value Sub-Attribute, the existing address
>            must be removed and the modified address added.
>            ...
>            {
>              "schemas": ["urn:scim:api:messages:2.0:PatchOp"],
>              "op":"replace",
>              "path":"addresses[type eq \"work\"].streetAddress",
>              "value":"911 Universal City Plaza"
>            }

Should the description be since we're not removing/adding:

    The following example shows how to change a User's street address.

> 3.4 "code":"404"

Many of the example error responses still use "code" instead of "status".  This should be changed to "status": 404.

> 3.5    The following Complex Multi-valued Attribute is defined in addition
>        to the common attributes defined in core schema.

Should just be "The following Complex Multi-valued Attribute is defined" since there are no common multi-valued attributes in the core schema.