SCIM Resource Schema and attribute proposal

[Trey Drake]

Proposal for fetching Resource schema.  The draft is also tacked on to issue #22 at http://code.google.com/p/scim/issues/attachmentText?id=22&aid=220004000&name=draft-scim-rest-api-01-7.html&token=d58f85db741f4e14a060fce9a021ff11

Thanks,

Trey

4.6.  Retrieving Service Provider Schema

The Resource schema endpoints enable Consumers to retrieve core and extended Resource meta-data providing Consumer implementers with sufficient information to perform Resource discovery.

Consumers may retrieve all Service Provider supported Resources via a GET request to the endpoint /Schemas. Service Providers MUST return all core and extended Resources within the response. The complete set of Resource schema attributes and associated usage is specified in the table below.

---

Attribute	Default value when omitted. If 'N/A' Service Providers MUST not specify a value.	Description
name	N/A	The Resource name. When applicable Service Providers MUST specify the name specified in the core schema specification.
description	N/A	The Resource's human readable description. When applicable Service Providers MUST specify the description specified in the core schema specification.
schema	urn:scim:schemas:core:1.0	The Resource's associated schema URN; e.g., urn:scim:schemas:core:1.0

Table 7: Resource Schema Attributes

---

An example request returning core Resources as well as a single extended Resource, 'Machine':

GET /schemas
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8

HTTP/1.1 200 OK
Content-Type: application/json
Location: https://example.com/schemas
{
  "resources":[
    {
      "name":"User",
      "description":"TBD",
      "schema":"urn:scim:schemas:core:1.0"
    },
    {
      "name":"Group",
      "description":"TBD",
      "schema":"urn:scim:schemas:core:1.0"
    },
    {
      "name":"Machine",
      "description":"An extended Resource",
      "schema":"urn:virtual:schemas"
    }
  ]
}

To retrieve a known Resource schema, Consumers send a GET request to /Schema/{Resource Name}; e.g., /Schema/User. If the Resource exists the Service Provider MUST return the schema in the body of the response with a 200 status code or, if non-existent, a 404 status code. If a core Resource; i.e., User or Group is extended the Service Provider must return the core Resource and all extended attributes. To avoid namespace collisions Resource extensions must be fully qualified by prefixing the Resource name with the associated schema URN; e.g., the Resource 'Machine' declared in the namespace 'urn:virtual:schemas' is represented as 'urn:virtual:schemas:Machine'.

Some schema attributes may be omitted and are context sensitive. The complete set of schema attributes and associated usage is specified in the table below.

---

Attribute	Applicability	Is Required	Default value when omitted. If 'N/A' Service Providers MUST not specify a value.	Description
name	all	true	N/A	The attribute's name.
type	all	false	string	The attribute's data type; e.g., string.
plural	Specify only if plural	false	false	Specifies if the attribute is a plural.
description	all	true	N/A	The attribute's human readable description. When applicable Service Providers MUST specify the description specified in the core schema specification.
schema	all	false	urn:scim:schemas:core:1.0	The attribute's associated schema; e.g., urn:scim:schemas:core:1.0.
readOnly	all	false	false	Specifies if the attribute is mutable.
required	all	false	false	Specifies if the attribute is required.
caseExact	Specify only if the attribute type is a string.	false	false	Specifies if the string attribute is case sensitive.
subAttributes	Specify only if the attribute is complex. If specified sub attributes MUST also be specified.	false	N/A	An array specifying the contained attributes.
pluralTypes	Specify only if the attribute is a Plural.	false	N/A	An array specifying the canonical type values. When applicable Service Providers MUST specify the canonical types specified in the core schema specification.

Table 8: Schema Attributes

---

A truncated, simple example using the core User Resource:

GET /schema/User/
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8

HTTP/1.1 200 OK
Content-Type: application/json
Location: https://example.com/schema/User
{
  "attributes":[
    {
      "name":"id",
      "description":"Unique identifier for the SCIM resource as defined by the Service Provider. Each representation of the resource MUST include a
      non-empty id value. This identifier MUST be unique across the Service Provider's entire set of resources. It MUST be a stable, non-reassignable
      identifier that does not change when the same resource is returned in subsequent requests. The value of the id attribute is always issued by the
      Service Provider and MUST never be specified by the Service Consumer. REQUIRED.",
      "readOnly":true
    },
    {
      "name":"name",
      "type":"complex",
      "description":"The components of the user's real name. Providers MAY return just the full name as a single string in the formatted sub-attribute, or
       they MAY return just the individual component attributes using the other sub-attributes, or they MAY return both. If both variants are returned, they
        SHOULD be describing the same name, with the formatted name indicating how the component attributes should be combined. OPTIONAL.",
      "subAttributes":[
        {
          "name":"formatted",
          "description":"The full name, including all middle names, titles, and suffixes as appropriate, formatted for display (e.g. Ms. Barbara J Jensen, III.). OPTIONAL."
        }
      ]
    },
    {
      "name":"emails",
      "type":"string",
      "plural":true,
      "description":"E-mail addresses for the user. The value SHOULD be canonicalized by the Service Provider, e.g. bje...@example.com instead of
      bje...@EXAMPLE.COM. Canonical Type values of work, home, and other. OPTIONAL.",
      "pluralTypes":["work","home","other"]
    }
  ]
}

[Hasini Gunasinghe]

Hi,

This addition is very useful since consumers may need to know the schemas and additional attributes of resources supported by service providers.

Would be great if I could get the following things clarified please...

[1] If we define additional attributes to User schema, and if we get a request of the first type above (i.e: GET /schemas) should we define each additional attribute as a resource in the response?
Or should we define our new User schema - say 'ExtendedUser' (which defines additional attributes) and include it as a separate resource in the response?
(In the first example above, since Machine is a separate resource, wanted to get clarified the approach regarding added attributes to core User schema.)

[2] Will these types of new additions be soon reflected in the drafts available at http://www.simplecloud.info/?

Thanks,
Hasini.

[Andrew Coulbeck]

This looks like a good start. I have the following comments.

1. Should we expect the XML representation of the SCIM schema to contain the same information? If so, this would not be sufficient to describe how SCIM attributes are represented in XML in resource requests. The XML schema is also required. I think it's important to answer this now in case it has wider implications. Currently, I'm assuming that the XML schema (scim-core.xsd) will become a normative part of the specification, but it is conspicuous by its absence right now.

2. This sentence doesn't make any sense to me: "Default value when omitted. If 'N/A' Service Providers MUST not specify a value.". I suggest that "If 'N/A' Service Providers MUST not specify a value" be deleted (from both tables), and add the "Is Required" column to the first table.

3. This is quite minor, but considering the quirks of the English language it would be nice to add an optional attribute on Resources that provides the query endpoint, for any case where the plural cannot be constructed by simply adding an 's' on to the resource name.

4. Are sub-attributes allowed to be plural or complex? I don't see a need for it. This is more a question for the core schema specification.

5. Will this schema representation be used in the core schema specification? I think it should.

6. I agree with Hasini's request for clarification about attribute extensions to resources. Please provide an example of how the SCIM enterprise extension is represented.

Thanks,

Andy

[Hasini Gunasinghe]

Hi again,

On Fri, Sep 9, 2011 at 10:24 AM, Hasini Gunasinghe <hasi...@gmail.com> wrote:

Hi,

This addition is very useful since consumers may need to know the schemas and additional attributes of resources supported by service providers.

Would be great if I could get the following things clarified please...

[1] If we define additional attributes to User schema, and if we get a request of the first type above (i.e: GET /schemas) should we define each additional attribute as a resource in the response?
Or should we define our new User schema - say 'ExtendedUser' (which defines additional attributes) and include it as a separate resource in the response?
(In the first example above, since Machine is a separate resource, wanted to get clarified the approach regarding added attributes to core User schema.)

Just to update that I got this clarified after reading through Core Schema [1] in detail. According to the Schema extension model defined there, all extensions are additive - similar to auxiliary objectClasses in LDAP. Therefore, they will be represented as different resources in the above case.

[1] http://www.simplecloud.info/specs/draft-scim-core-schema-01.html

Thanks,
Hasini.

[Trey Drake]

On Sep 9, 2011, at 11:13 AM, Andrew Coulbeck wrote:

This looks like a good start. I have the following comments.

1. Should we expect the XML representation of the SCIM schema to contain the same information?

Yes.

If so, this would not be sufficient to describe how SCIM attributes are represented in XML in resource requests. The XML schema is also required. I think it's important to answer this now in case it has wider implications.

Can you point out what data is missing?  I do agree without a normative schema (see below) its rather difficult to ensure the payloads look and feel the same; e.g., a classic case is expressing attributes as sub-elements <foo><bar>baz</bar><foo> vs  attributes <foo bar="baz"/>.

Currently, I'm assuming that the XML schema (scim-core.xsd) will become a normative part of the specification, but it is conspicuous by its absence right now.

Its actually not absent  and we've agreed on previous conf-calls to make the schema normative once the spec is complete.  Its checked into SVN (see website/specs) though needs someone to link it up with the core schema spec.  Volunteers?  

2. This sentence doesn't make any sense to me: "Default value when omitted. If 'N/A' Service Providers MUST not specify a value.". I suggest that "If 'N/A' Service Providers MUST not specify a value" be deleted (from both tables), and add the "Is Required" column to the first table.

The first table shouldn't have the column at all as they are all required.  Copy-n-paste what can I say.  As for table 2 how would you prefer to describe the default values for name, description, subattributes, and pluraltypes?  In those cases there aren't any legitimate default values.  The purpose of this language is to simply allow Service Providers to omit attributes that, given the core schema spec, rarely differ from the default value.

3. This is quite minor, but considering the quirks of the English language it would be nice to add an optional attribute on Resources that provides the query endpoint, for any case where the plural cannot be constructed by simply adding an 's' on to the resource name.

Sure.

4. Are sub-attributes allowed to be plural or complex? I don't see a need for it. This is more a question for the core schema specification.

This is a matter for the core schema spec.  Chuck, others?  I'd prefer to prohibit this as well, but I'm curious as to what a nested Group looks like.  

5. Will this schema representation be used in the core schema specification? I think it should.

Do you mean the format and description should be specified in the core schema spec?  I agree that it should.  Any volunteers to make it so?

6. I agree with Hasini's request for clarification about attribute extensions to resources. Please provide an example of how the SCIM enterprise extension is represented.

Sure.

Thanks for the feedback,

Trey

[Andrew Coulbeck]

On Sep 9, 2011, at 2:05 PM, Trey Drake wrote:

On Sep 9, 2011, at 11:13 AM, Andrew Coulbeck wrote:

This looks like a good start. I have the following comments.

1. Should we expect the XML representation of the SCIM schema to contain the same information?

Yes.

If so, this would not be sufficient to describe how SCIM attributes are represented in XML in resource requests. The XML schema is also required. I think it's important to answer this now in case it has wider implications.

Can you point out what data is missing?  I do agree without a normative schema (see below) its rather difficult to ensure the payloads look and feel the same; e.g., a classic case is expressing attributes as sub-elements <foo><bar>baz</bar><foo> vs  attributes <foo bar="baz"/>.

Take for example the addresses attribute, which is between photoUrls and memberOf in the XML schema :

          <xs:element name="addresses" minOccurs="0">

            <xs:complexType>

              <xs:sequence>

                <xs:element name="address" type="tns:address"

                            minOccurs="0"

                            maxOccurs="unbounded"/>

              </xs:sequence>

            </xs:complexType>

          </xs:element>

The element name "address" is information that is only found in the XML schema. The fact that the addresses element is supposed to come after photoUrls and before memberOf is also information that is only found in the XML schema. If it was up to me, I would do away with XML completely but I know that isn't going to happen.

Currently, I'm assuming that the XML schema (scim-core.xsd) will become a normative part of the specification, but it is conspicuous by its absence right now.

Its actually not absent  and we've agreed on previous conf-calls to make the schema normative once the spec is complete.  Its checked into SVN (see website/specs) though needs someone to link it up with the core schema spec.  Volunteers?  

2. This sentence doesn't make any sense to me: "Default value when omitted. If 'N/A' Service Providers MUST not specify a value.". I suggest that "If 'N/A' Service Providers MUST not specify a value" be deleted (from both tables), and add the "Is Required" column to the first table.

The first table shouldn't have the column at all as they are all required.  Copy-n-paste what can I say.  As for table 2 how would you prefer to describe the default values for name, description, subattributes, and pluraltypes?  In those cases there aren't any legitimate default values.  The purpose of this language is to simply allow Service Providers to omit attributes that, given the core schema spec, rarely differ from the default value.

I am just asking to delete the sentence "If 'N/A' Service Providers MUST not specify a value" from the column heading.

Andy

[Trey Drake]

Please see inlined.

On Sep 9, 2011, at 11:30 AM, Hasini Gunasinghe wrote:

Hi again,

On Fri, Sep 9, 2011 at 10:24 AM, Hasini Gunasinghe <hasi...@gmail.com> wrote:

Hi,

This addition is very useful since consumers may need to know the schemas and additional attributes of resources supported by service providers.

Would be great if I could get the following things clarified please...

[1] If we define additional attributes to User schema, and if we get a request of the first type above (i.e: GET /schemas) should we define each additional attribute as a resource in the response?

No.  In the proposal the Service Provider returns the User schema with the core and extended attributes in the same response.  See the example below with the extended 'age' attribute.

    },

    {

      "name":"age",

      "description":"The numeric user age. OPTIONAL.",

      "schema":"urn:hr:schemas:user"

    },

  ]

}

The idea is to wire extensions directly into the Resource versus fetching schemas and then determining their applicability to Resources.  The upside is, IMO, this is as dead simple as it gets.  The downside is Consumers must iterate all Resources to discover all extended schemas.   Is there any utility in adding a schema namespace specific endpoint;?  I don't see it at the moment.

Or should we define our new User schema - say 'ExtendedUser' (which defines additional attributes) and include it as a separate resource in the response?

(In the first example above, since Machine is a separate resource, wanted to get clarified the approach regarding added attributes to core User schema.)

Just to update that I got this clarified after reading through Core Schema [1] in detail. According to the Schema extension model defined there, all extensions are additive - similar to auxiliary objectClasses in LDAP. Therefore, they will be represented as different resources in the above case.

I see your point.  Perhaps the core schema spec language should be clarified.  The lens I'm looking through is the same one I use when fetching a /User resource.  That is, a GET to /User retrieves the core User + any extended attributes.    

[1] http://www.simplecloud.info/specs/draft-scim-core-schema-01.html

Thanks,
Hasini.

[2] Will these types of new additions be soon reflected in the drafts available at http://www.simplecloud.info/?

Yes, once the proposal has had a week or so to circulate and there are no outstanding issues.

Thanks,

Trey