Subject: Re: [Gen-art] Gen-art last call review of draft-ietf-scim-core-schema-17

From: Elwyn Davies <[email-masked]>
Date: Wed, 06 May 2015 17:18:30 +0100

Hi, Phil.

Thanks for the response and the updated draft.

I'll bite my tongue and defer to past history and the WG consensus on 
the internationalization issues.  IMO this area is something that needs 
to be considered for other (new) specifications so that we don't remain 
ossified and adhering to a US/UK English paradigm that doesn't really 
fit other locales.  But, as I said, this draft goes ahead as is on that 
front.

There are some remaining minor comments on the updated draft inline 
below.  If you don't get around to generating a new draft before the 
telechat, I'll send these as my telechat review.

Regards,
Elwyn

On 20/04/2015 19:30, Phil Hunt wrote:
> Elwyn,
>
> Thanks for your careful and thorough review.  I have included my comments below.
>
> Note, if I have not commented below, please assume I agree with your comment and will update the draft to include your feedback.
>
> Discussion inline below...
>
> Phil
>
> [email-masked]
>
>> On Apr 17, 2015, at 2:26 PM, Elwyn Davies <[email-masked]> wrote:
>>
>> I am the assigned Gen-ART reviewer for this draft. For background on
>> Gen-ART, please see the FAQ at
>>
>> <http://wiki.tools.ietf.org/area/gen/trac/wiki/GenArtfaq>.
>>
>> Please resolve these comments along with any other Last Call comments
>> you may receive.
>>
>> Document: draft-ietf-scim-core-schema-17.txt
>> Reviewer: Elwyn Davies
>> Review Date: 2015/04/09
>> IETF LC End Date: 2015/04/20
>> IESG Telechat date: (if known) -
>>
>> Summary: Not ready.  The 'major' issue identified is really political rather than strictly technical although the proposed syntax does limit the applicability (or at least the easy applicability) of the scheme. Making the schemas more aware of practice outside the basic English speaking world should be an aim of IETF work, IMO.  The minor issues are mostly  only just more than editorial nits - and there are quite a few of these also.
>>
>> Major issues:
>> ===========
>> s4.1.1, "name" attribute:  The definition of this attribute is culturally insensitive.  The
>> collection of name sub-attribute terms are North American/UK/Aussie/NZ English -speaking biased.  The authors might wish to consider http://www.w3.org/International/questions/qa-personal-names.
> [PH] I am not sure I agree with your conclusion. SCIM is a provisioning protocol and not a rendering protocol. SCIM is concerned with conveying information between systems based on commonly used fields. Further for formatted name, there is no restriction on how the name may be structured. Essentially SCIM already follows the above reference. Note that we don’t use a regional identifier in name, but rather have it as a separate attribute “locale”. This enables a UI to render the name in the appropriate regional method.
>
> The WG did have several international participants and no issues were raised.
>
> I believe that what is being reflected is that while database structures and schemas tend to be “western” oriented, there are well trodden industry practices to map those fields to render user facing material in the proper localized forms.
>
> In deference to your concern over the weekend, I re-raised the issue with Oracle developers and have been informed that there has been an internationalization review and the specification does not present any problems for us as international implementers.
>
>> To a lesser extent this also applies to the definition of the addresses attribute in s4.1.2.  The issue of the representation of postal addresses incorporated in I-Ds and RFCs in the xml2rfc schema has been debated at length on the rfc-interest mailing list.  The new (v3) vocabulary replaces the specific sub-attributes with an ordered  list of "postalLine" elements (see https://tools.ietf.org/html/draft-hoffman-xml2rfc-16#section-2.39). Further, the use of country codes in RFCs has been dropped some time ago.  It might be better to represent the address in a less specific way and leave display up to user interfaces that can consider the relevant locale.  My suggestion, FWIW, would be to have a country, possibly a code field plus an ordered array of postalLines that can contain any of the additional components and cater for any locale specific format.
> [PH] The suggested workaround of following the format for XML2RFC using an array of “postalLine” values causes more problems in the current SCIM model:
> 1.  SCIM does not support array references (e.g. postalLine/1, postalLine/2). In some cases, the order of elements may not be guaranteed by some impelementers (e.g. those building on top of LDAP)
> 2.  SCIM’s objective is to provision. So the meaning associated with the field must be well known to map it to the receivers data system. A system line postalLine1, postalLine2 would require attribute parsing which is substantially more complex and unreliable given the wide variance.
> 3.  In practice, international data is collected through a user-interface which then categorizes the input and maps them to the appropriate attributes.  If we introduce agnostic attribute naming in the protocol (postalAddress1, 2 etc) we actually lose knowledge of what the intended content is.  This means that it becomes impractical to say does postalAddress2 map to city, county, district, or mail stop of a target system.
>
> IOW. In the XML2RFC, we depend on human editors to validate and align the data. As a protocol we do not have this luxury.
As per my comment at the top, I withdraw these comments and defer to the 
WG consensus.
>
>
>> ======================================================
>>
>> Minor issues:
>> ===========
>> Reference to SCIM Protocol document:  At a bare minimum a normative reference to the SCIM protocol document (currently draft-ietf-scim-api-16) is needed in s1.2 where the protocol is referred to in the first two definitions.  In my opinion, this document would be improved by the addition of a brief overview of the operation of the SCIM protocol and the implications for the design of the schema.   For example, s2 talks about 'replacement of a resource':  Knowing in advance that one of the operations anticipated in the protocol is replacement makes this clearer.
My feeling is still that a brief overview of the SCIM protocol would 
help. Maybe something like inserted
befoee the last para of s1:
    The SCIM Protocol is an application-level protocol for provisioning 
and managing identity data
    specified through the SCIM schemas.  The protocol supports creation, 
modification, retrieval,
    and discovery of core identity resources such as Users and Groups, 
using a subset of the HTML
    methods (GET for retrieval of resources, POST for creation, 
searching and bulk modification, PUT for
    attribute replacement within resources, PATCH for partial update of 
attributes, and DELETE for
    removing resources).

> No objection. There has been a practical problem that XML2RFC won’t let you reference a draft version that does not exist. In practice we’ve had to publish API 2 days after core-schema in order to allow the validation to succeed.  I will amend the document and leave notes for the RFC editor to co-publish the specs since they reference each other.
That will happen automatically - the documents form a RFC editor 'queue 
cluster' because of the references.  This shouldn't be a big deal since 
they are going through IESG at the same time.

>> s1.1, Use of OPTIONAL and REQUIRED:  These terms are overloaded in this document.  The majority of uses are not specifying features of the protocol as per RFC 2119 but indicating the necessity or otherwise of the presence of particular attributes in resource types.  AFAICS the only RFC 2119 usages are one place in  s2.2.7 for OPTIONAL  and two adjacent places in s10.3.1 for REQUIRED .   To avoid the overloading it would be easy to omit OPTIONAL and REQUIRED from the RFC 2119 list, use the alternative RFC 2119 terminology (MAY in s2.2.7 and MUST in s10.3.1) and provide a separate note on the usage of OPTIONAL and REQUIRED in s1.1.
> [PH] In the context of a schema document, the use of OPTIONAL and REQUIRED is equivalent to protocol normative language and was intended.
>
> Never-the-less, if you feel strongly, I can re-word to avoid RFC2119 language entirely.
This is a difficult one.  When used as qualifiers for attributes they 
have implications for both implementers and end users.
REQUIRED is not a big deal:  Implementers MUST implement it and users 
MUST use it, so 2119 language is no problem.
OPTIONAL is a bit more difficult. Does an implementer have to implement 
the OPTIONAL attribute?  If the OPTIONAL attribute is implemented in a 
particular implementation, MUST the end user supply a value? And vice 
versa.
>> s2.1, Syntax of attribute names:  I am confused by the constraints suggested here.
>> (1)   "Attribute names SHOULD be camel-cased":  AFAICS this has no impact on the specification or protocol.  My guess is that the specification has adopted the convention normally used in JavaScript.  This is merely a representation of the convention used in SCIM schemas and RFC 2119 language is inappropriate.  I suggest replacing this with
>> "This document uses the camel-casing convention for attribute names (e.g., "camelCase").
>> (2) "nameChar   = "-" / "_" / DIGIT / ALPHA": Given the close association with JavaScript, it seems inappropriate to allow hyphen (-) as a character in attribute names as this is illegal in JavaScript.
>> (3) The definition should say whether attribute names are case sensitive.
> [PH] I will clarify.  Attribute names should be case-insensitive.
OK.  New text looks good.
>
>
>> (4) Even though there is ABNF, it would be useful to note explicitly that names are limited to a subset of ASCII rather than the much wider JSON string or JavaScript variable character sets.
> [PH] As the document references the core rules in RFC5234.  Are you suggesting we should restrict to A-Z / a-z rather than ALPHA?
I think the revision is OK.
>> s2.2.7, $ref:  In s2.2.7, $ref is defined as a sub-attribute name but does not match the attribute name syntax discussed in the previous comment for s2.1.  Does the attribute name syntax apply to sub -attributes?  Or are they just JSON member names?
> The ABNF should be
>
> ATTRNAME   = ALPHA *(nameChar)
> nameChar   = “$” / “-" / "_" / DIGIT / ALPHA
>
> Note:  there is no requirement that javascript attribute names must be exactly the same as JSON payload attribute names. So while “-“ may be problematic in Javascript (they need to be escaped), I see no protocol impacts and suggest we not eliminate “-“ (hypen) from attribute names at this time.
As I understand it, you can treat a JSON object as what would be a 
(declared) structure or object in other languages and use the element 
names directly in code to access the components of the JSON object.  
This won't work if the names contain "-".  Of course this won't upset 
the protocol but I am not sure if there would be any way to escape the 
hyphen in the Javascript.  Maybe just a note to warn people of the 
pitfall since Javascript seems to be the language of choice in client 
side browser programming these days?
>> s2.3, next to last para:  To ensure that the service provider knows what it ought to do to canonicalize a given value, the schema specification needs to specify what canonicalization means for each type of attribute.  Having read further on, I see that this is done in most cases for relevant attributes defined in this draft.   A note that this should be done generally when defining new schemas is needed here.  This is particularly important for strings that might have internationalization issues (c.f., the discussion of string comparison in filtering in section 5 of draft-ietf-scim-api-16.)
>>
>> s7, canonicalValues:  The wording here
>>>          When
>>>          applicable service providers MUST specify the canonical types
>>>          specified in the core schema specification; e.g., "work",
>>>          "home".
>> seems to imply that the possible canonicalValues mentioned in the definitions of User, Group etc.  schemas earlier in the draft are actually normative minimum requirements that could, at least in some cases, be extended.  The wording used in the earlier sections is rather less definitive and appears to indicate that the suggested values are examples that a service provider might possible want to replace if they considered alternative values better suited to their application, e.g.
>>>    userType
>>>       Used to identify the organization to user relationship. Typical
>>>       values used might be "Contractor", "Employee", "Intern", "Temp",
>>>       "External", and "Unknown" but any value may be used.
>> and
>>>    phoneNumbers
>>>       Phone numbers for the user.   ...  The "display" sub-attribute
>>>       MAY be used to return the canonicalized representation of the
>>>       phone number value.  The sub-attribute "type" often has typical
>>>       values of "work", "home", "mobile", "fax", "pager", and "other",
>>>       and MAY allow more types to be defined by the SCIM clients.
>> The wording used in the earlier sections seems to need 'tightening up' to make it clear what minimum set of canonicalValues is required for conformance, if indeed that is what is wanted.
> [PH] Agreed. Suggestion:
>
> A collection of suggested values for an attribute. For example often used with the “type” attribute to categorize a value such as “home” or “work”.  The service provider MAY choose to ignore values it does not support.
This helps.  The wording in s4.1.2 needs a little more work (see other 
email).
>> s7, caseExact:  I think you may need to clarify what case insensitivity means for languages other than unaccented English.  It may be sufficient to provide a note and a pointer to the discussion of filtering and normalization in the protocol draft.
OK.
>>
>> s10.3:  The registration procedure seems overly complex.  If, as stated, an RFC is required in all cases, then the standard (RFC 7035) IETF Review registration policy would seem to fill the bill and there is no need for a designated expert.  Alternatively, Specification Required (with a designated expert as is standard for this case) could be used if other types of specification could be countenanced.  I suspect the requirement for a standards track RFC as a way of modifying an existing value is going to come back to bite us if the original specification was not standards track.  I am not sure this attempt to provide a higher hurdle for modifications is the best way to go about this - In general, IETF Review would, I think, give enough pushback against inappropriate updates without requiring standards track in all cases.  Overall, I recommend that the authors consult your AD and IANA to determine how best to structure the registration procedure.
> [PH] The current document is probably following older IANA practices which I understand have recently been updated. Leif Johansson has suggested we can simplify by updating the document to reflect the new recommendations. I’ll let Leif comment more on this issue.
OK.
>> ===========================================================
>>
>> Nits/editorial comments:
>> =====================
>> Global: s/e.g. /e.g., /
>>
>> The term 'endpoint': The term '(network) endpoint' has a particular technical meaning in W3C/HTTP jargon although it the usage in (e.g.) http://www.w3.org/TR/wsdl.html seems rather self-referential.  It would be useful to provide a definition.  Perhaps something like:
>> (Network) endpoint:  Also known as a 'port' (see http://www.w3.org/TR/wsdl.html).  A  port has a 'port type' that identifies a set of operations invoked by HTTP methods.  Each port is identified by a URI  typically constructed from the base URI identifying the server implementing the operation and a relative URI bound to the port type.  The methods are associated with abstract data types, such as the schema specified in this document.  HTTP messages carry data structured according to the abstract data types.
>>
>> Canonicalized URLs:   Presumably URLs should be canonicalized in line with Section 6 of RFC 3986.  An appropriate global place to say this would be s2.3 I believe.   However RFC 6986 offers a 'ladder' of canonicalizations and it would be desirable to say what rung on this ladder should be used.  Presumably either 6.2.3 or 6.2.4.
>>
>> s1, para 1, last sentence:  The phrase 'redundantly integrated' is not felicitous.  Suggestion:
>>
>> OLD:
>>    Similarly, cloud services
>>    providers seeking to inter-operate with multiple application
>>    marketplaces or cloud identity providers must be redundantly
>>    integrated.
>> NEW:
>>    Similarly, cloud services
>>    providers seeking to inter-operate with multiple application
>>    marketplaces or cloud identity providers would require pairwise
>>    integration.
>> END
>>
>> s1, para 2: Worth adding a reference to [PortableContacts] since you have it already and its not a 'well-known' item.
OK
>> I fear that LDAP is not a well-known abbreviation within the meaning of the act, and needs expanding.
This still needs expanding.
>> Maybe add a ref to RFC 6350 for vCards.
>>
>> s2, para 1, 1st sentence: s/contents of which/allowable contents of which/
>> s2, para 1, 4th sentence: s/alidation/Validation/
>>
>> s2, para 1, last sentence: s/the attributed defined schema/its characteristics as defined in the relevant schema/
>>
>> s2, para 2: s/extend schema/ extend a schema/ [or "extend schemas"]
>>
>> s2.1, para 1: s/For each attribute, SCIM schema/For each attribute, a SCIM schema/
>>
>> s2.2:  The list of characteristics and their default values is not associated with the data type of the attribute but is another set of attributes of each attribute defined.  This would be clearer if the list of defaults and examples was separated out into a new section (probably after s2.2).  It would be helpful to point out explicitly that these defaults apply to all the attributes defined in the draft - I found the tacit assumption of default characteristics in later definitions of attributes had me asking myself whether certain characteristics ought to have been defined whereas they were actually covered by the defaults.
Fine... but I think reversing the order of s2.2 and the (new) s2.3 would 
help as some of the items defined in s2.3 are referred to in s2.2.
>>
>> s2.2, 1st bullet: For consistency, s/required/REQUIRED/
>>
>> s2.2, bullet 5:
>> OLD:
>> o  have no canonical values (e.g. type is "home" or "work"),
>> NEW:
>> o  have no canonical values (for example, the "type" sub-attribute in Section 2.3),
>> END
>>
>> s2.2.6, Base 64 URL encoding:  Presumably the trailing padding characters can be omitted here - this should be mentioned whether or not they are needed.
OK
>>
>> s2.2.8: Presumably, in line with s2.3 and the JSON specification, the order of component attributes is not significant.  If this is so, it should be mentioned here:  Perhaps add:
>>     The order of the component attributes is not significant. Servers and
>>     clients MUST NOT require or expect attributes to be in
>>     any specific order when an object is either generated or analyzed.
OK
>>
>> s2.3, 1st para:  I found this difficult to parse.  Suggest:
>> OLD:
>>    Multi-valued attributes contain a list of value or may contain sub-
>>    attributes and MAY also be considered complex attributes.  The order
>>    of values returned by the server SHOULD NOT be guaranteed.  The sub-
>>    attributes below are considered normative and when specified SHOULD
>>    be used as defined.
>> NEW:
>>     Multi-valued attributes contain a list of elements, using the JSON array format
>>     defined in Section 5 of [RFC7159].  Elements can be either
>>     o   primitive values, or
>>     o   objects with a set of sub-attributes and values, using the JSON object format
>>          defined in Section 4 of [RFC7159], in which case they MAY also be considered
>>          to be complex attributes.  As with complex attributes, the order of sub-attributes
>>          is not significant.  The pre-defined sub-attributes listed in this section can be
>>         used with multi-valued attribute objects but these sub-attributes should only be used
>>        with the meanings as defined here.
>>
>> s2.3: Question: Can sub-attributes have sub-sub-attributes?  I don't think I see any examples and maybe the definition in s1.2 effectively excludes them.  Might be worth being explicit.
> [PH] Agreed. I will add text that complex attributes may not have complex sub-attributes (sub-sub-attributes).
Great.   Thinking again about this.. perhaps 'should only be used' ought 
to be 'MUST only be used'?
>
>> s2.3, "primary" sub-attribute: Should this be specified as assumed to be "false" if not present in a relevant object?  I don't think this is covered by the defaults anywhere.
> Agreed.
>> s2.3, $ref: I guess this ought always to be canonicalized  - this can be noted in the following paragraph where canonicalization is discussed.  This would be a good place to specify a reference for URL canonicalization as mentioned above.
The default method and level of canonicalization for URLs (especially 
for $ref) still needs to be specified. I suspect (RFC 3986, section 
6.2.x, where the 'x' is between 1 and 4 according to what you consider 
appropriate.)
>>
>> s2.3, last para: Suggest being a little more explicit about the scope of this paragraph.  I suggest:
>> OLD:
>>    Service providers MAY return the same value more than once with
>>    different types (e.g. the same e-mail address may used for work and
>>    home), but SHOULD NOT return the same (type, value) combination more
>>    than once per Attribute, as this complicates processing by the
>>    Consumer.
>> NEW:
>>    Service providers MAY return element objects with the same "value" sub-attribute
>>    more than once with a  different "type" sub-attribute (e.g., the same e-mail address
>>    may used for work and home), but SHOULD NOT return the same (type, value)
>>    combination more than once per Attribute, as this complicates processing by the
>>    consumer.
>> END
>> Note "Consumer" replaced by "consumer" - there is no definition of a specific meaning for this term.
OK
>>
>> s3, Resource Type:  s/("meta.resourceType")/("meta.resourceType", see Section 3.1)/
OK
>>
>> s3, Schemas Attribute:  I think s/the namespace of SCIM schema that defines/the namespaces of the SCIM schemas that define/; s/All representations of SCIM schema MUST include a non-zero value array/All representations of SCIM schemas MUST include a non-empty array/
OK
>>
>> s3, name used in example:  I don't know if the RFC Editor has a policy on suitable fictitious names equivalent to example.com for domains.  Apparently Jane Roe and Mary Major have been used in US legal practice  as female alternatives to the ubiquitous Mr John Doe.  Probably good to check with the RFC Editor.
Pass...
>>
>> s3.1, id, externalId, meta.version, meta.resourceType:  I suspect these ought to be caseExact?
>>
>> s3.1, externalId:  The concepts of "provisioning domain" and a "client's tenant" need to be defined.  The externalId attribute is not explicitly defined as REQUIRED or OPTIONAL.
I noticed that making externalId OPTIONAL probably conflicts with the 
'MUST be included' statement in para 1 of s3.1.
It might be clearer to say that they are all REQUIRED (or otherwise) 
assuming that is what is meant by 'MUST be included'.
It isn't clear whether this MUST statement applies to the sub-attributes 
in 'meta' - and if it does there may be a conflict.
>>
>> s3.1.1, meta.resource:  I got the impression from s3 that meta.resourceType was REQUIRED rather than being optional as noted in the first para of s3.1.1.
OK
>>
>> s3.1.1, meta.location: Should the value of this sub-attribute be the same as Content-Location rather than Location?  Is it intended that the request should be redirected (or that the resource was newly created?  If not it seems Content-Location would be more appropriate.  A normative reference to the relevant HTTP RFC (probably RFC 7231) ought to be included.
OK
>>
>> s3.1.1, meta.version:  Would one expect a weak or strong ETag?  A normative reference to the relevant HTTP RFC (probably RFC 7232) ought to be included.
OK
>>
>> s3.2, last sentence: s/Section 6and/Section 6 and/ (missing space).
OK
>>
>> s3.3, 1st para:    s/used in LDAP/are used in LDAP/;
>>                             s/Each "schemas" value indicates additive schema/Each value in the "schemas" attribute  indicates an additive schema/;
>>                             s/See Figure 5 for an example JSON representation/See Figure 5 for an example of the JSON representation/
OK
>>
>> s3.3, para 2: s/"schemas" URI value/URI value in the "schemas" attribute/
OK
>>
>> s4.1.1, userName:  Having said that each User MUST have  include a non-empty userName value, why is this attribute RECOMMENDED rather than REQUIRED?  I guess it ought to be caseExact also.
OK
>>
>> s4.1.1, profileUrl: Needs a canonicalization mechanism specified.
The default format definition.. but it still needs a canonicalization 
mechanism (see comment above for s2.3, $ref)
>>
>> s4.1.1, preferredLanguage:  There is potentially more than one preferred language (as per Accept-Languages) so this presumably this ought to be a Multi-valued attribute.  The Accept-Language header syntax also has an optional, per language, weight to assist with selection.  Should this be catered for here as well?  This would presumably mean that it should have sub-attributes (e.g.) using "value" for the name and "weight" or some such.
OK.. we have multiple values... so shouldn't this move to the 
Multi-valued Attributes section (s4.1.2)?
>>   Also s/localized User interface/localized user interface/
This one got missed.
>> s4.1.1, password:  I *hope* there is a discussion of the security implications of this field later.  A pointer to this discussion would be highly desirable.
OK
>>
>> s4.1.2, photos: A reference to the canonicalization mechanism is needed (see previous comment).
Still needed.
>>
>> s4.1.2, entitlements, roles: There doesn't seem to be any good reason for capitalizing 'NO' here: s/NO/no/, 2 places.
OK
>>
>> s4.2, para 2: s/by the service provider are considered/by the service provider, and are considered/
OK
>>
>> s4.3, employeeNumber:  Maybe this might be better called an "employeeIdentifier" since it can be alphanumeric.  Is there any reason why this can't just be any old string?
OK
>>
>> s5, patch: A pointer to the SCIM protocol draft PATCH operation would be helpful.
OK
>>
>> s5, bulk: A pointer to the SCIM protocol draft Bulk operations section would be helpful.  I note that the capitalized form is not used in the protocol draft: suggest s/BULK/Bulk/ (total of 2 places)
The cross reference would probably be better on the top level item 
'bulk' rather than on the 'supported' sub-attribute.
>>
>> s5, filter: A pointer to some appropriate part of the SCIM protocol draft  (maybe s3.4.2.2) would be helpful.
OK
>>
>> s6, endpoint:  (1)The endpoint is defined to be a relative URI.   It is therefore inappropriate that the example here is "/Users".  I guess it ought to be "Users".  There are a number of example of relative URIs starting with / in the examples in Section 8 that also ought to be corrected.
There are a couple of examples of '"$ref": "/Groups...."' and '"$ref": 
"/Users.."' in s8.3; '"endpoint":  "/Users"' and '"endpoint":  
"/Groups"' in s8.6;  and in the definition of endpoint in s1.2 there is 
"/Schemas" which all ought to be relative URLs.
>>
>> s6, endpoint: (2) Please bear with me, this is a bit long winded... I initially thought that the 'endpoint' mechanism was a possible contravention of BCP 190/RFC 7320:  Quoting s2.3 of RFC 7320:
>>>     Scheme definitions define the presence, format, and semantics of a
>>>     path component in URIs; all other specifications MUST NOT constrain,
>>>     or define the structure or the semantics for any path component.
>>>
>>>     ....
>>>
>>>     For example, an application ought not specify a fixed URI path
>>>     "/myapp", since this usurps the host's control of that space.
>>>
>>>     Specifying a fixed path relative to another (e.g., {whatever}/myapp)
>>>     is also bad practice (even if "whatever" is discovered as suggested
>>>     in Section 3); while doing so might prevent collisions, it does not
>>>     avoid the potential for operational difficulties (for example, an
>>>     implementation that prefers to use query processing instead, because
>>>     of implementation constraints).
>> In Section 6, the definition of the endpoint attribute specifies that each schema has to declare a relative URI or path component that gives access to schema instances.  My initial thinking was that  the endpoint value was standardized for Users and Groups in the draft.  My interpretation of s2.3 of RFC 7320 was that this technique is deprecated as bad practice.  After sleeping on it, I think I understand that the endpoint value is *not* standardized and potentially each service provider can use a different endpoint name if they really have to (although I guess in this case it would be good to go with the defaults.)  So I am happy that this isn't flagrantly contravening BCP 190, although I am not sure about the query processing bit at the end of the quoted section.  Conclusion: I think it would be useful to add a note to the definition of endpoint to indicate that it is at the choice of the service delivering the resources and is not a fixed value, maybe saying that this is intended to avoid infringing BCP 190.
Phil's note indicated that he agreed with this but a note hasn't been added.
>>
>> s7, mutability:
>> OLD:
>> mutability  A single keyword indicating what types of
>>                     modifications an attribute MAY accept as follows:
>> This 'MAY' is not about the 'protocol'.. Suggest:
>> NEW:
>> mutability  A single keyword indicating the circumstances under
>>                     which the value of the attribute can be (re)defined:
>> END
OK
>>
>> s9: s/personally identifiable information/personally identifying information/g
There is an instance in s9.3 para 2 still.
>>
>> s9, 1st bullet: s/mulitple/multiple/
Ok.. but, I suggested providing a definition for 'tenant' back in s3.1.  
The updated draft removed 'tenant' from s3.1 rather than providing a 
definition, so the original comment now applies to the first bullet of s9.3.
>>
>> s9: para 1:  It would be sensible to also forbid the carrying of passwords in requests that are not encrypted.
(handed off to api draft - fine)
>>
>> s9:  It would be worth emphasizing that privacy issues should be considered whenever resource extensions are defined.
OK
>>
>> s10.1:  This is a request for a new entry in the  'URN Sub-namespace for Registered Protocol Parameter Identifiers' ...
>> OLD:
>>    IANA has created a registry for new IETF URN sub-namespaces,
>>    "urn:ietf:params:scim:", per [RFC3553].  The registration request is
>>    as follows:
>>
>>    Per [RFC3553], IANA has registered a new URN sub-namespace,
>>    "urn:ietf:params:scim".
>> NEW:
>>    IANA is requested to add an entry to the 'IETF URN Sub-namespace for Registered Protocol Parameter Identifiers'
>>    registry and create a sub-namespace for the Registered Parameter Identifier as per [RFC3553]:
>>    "urn:ietf:params:scim:".
>>    The registration request is as follows:
>> END
>>
>> s10.2:   This section is lacking a specification of exactly what is recorded in the new SCIM registry - the template tells how to apply and considerations to be used in granting the request.  See Section 8.4 of RFC 7035, for example, to see what is needed here.
IANA updates in progress - fine.
>>
>>
>> s11.1: Needs a reference to the SCIM protocol document.
OK
>>
>> s11.2, [Olson-TZ] is  incomplete - I suspect it needs a reference to the IANA TZ database http://www.iana.org/time-zones
Adding the URL would be helpful (<ref... 
target="http://www.iana.org/time-zones"> if using xml2rfc)

---

From: Phil Hunt <[email-masked]>
Date: Wed, 6 May 2015 09:42:02 -0700

Thanks Elwyn for your thorough review. Much appreciated. 

Yes I agree with your comment re internationalization. I would think a best practice would be very helpful to move the industry.  I guess as a provisioning spec we are stuck having to deal with ossification since we have to map legacy anglo structures. 

I plan to update very soon pending ok from Kathleen and the group on some other issues. 

Thanks!

Phil

> On May 6, 2015, at 09:18, Elwyn Davies <[email-masked]> wrote:
> 
> Hi, Phil.
> 
> I'll bite my tongue and defer to past history and the WG consensus on the internationalization issues.  IMO this area is something that needs to be considered for other (new) specifications so that we don't remain ossified and adhering to a US/UK English paradigm that doesn't really fit other locales.  But, as I said, this draft goes ahead as is on that front.
> 
> There are some remaining minor comments on the updated draft inline below.  If you don't get around to generating a new draft before the telechat, I'll send these as my telechat review.
> 
> Regards,
> Elwyn
> 
> 
> As per my comment at the top, I withdraw these comments and defer to the WG consensus.
>> 
>> 
> My feeling is still that a brief overview of the SCIM protocol would help. Maybe something like inserted
>   The SCIM Protocol is an application-level protocol for provisioning and managing identity data
>   specified through the SCIM schemas.  The protocol supports creation, modification, retrieval,
>   and discovery of core identity resources such as Users and Groups, using a subset of the HTML
>   methods (GET for retrieval of resources, POST for creation, searching and bulk modification, PUT for
>   attribute replacement within resources, PATCH for partial update of attributes, and DELETE for
>   removing resources).
> 
> That will happen automatically - the documents form a RFC editor 'queue cluster' because of the references.  This shouldn't be a big deal since they are going through IESG at the same time.
> 
> This is a difficult one.  When used as qualifiers for attributes they have implications for both implementers and end users.
> REQUIRED is not a big deal:  Implementers MUST implement it and users MUST use it, so 2119 language is no problem.
> OPTIONAL is a bit more difficult. Does an implementer have to implement the OPTIONAL attribute?  If the OPTIONAL attribute is implemented in a particular implementation, MUST the end user supply a value? And vice versa.
> As I understand it, you can treat a JSON object as what would be a (declared) structure or object in other languages and use the element names directly in code to access the components of the JSON object.  This won't work if the names contain "-".  Of course this won't upset the protocol but I am not sure if there would be any way to escape the hyphen in the Javascript.  Maybe just a note to warn people of the pitfall since Javascript seems to be the language of choice in client side browser programming these days?
> This helps.  The wording in s4.1.2 needs a little more work (see other email).
> Fine... but I think reversing the order of s2.2 and the (new) s2.3 would help as some of the items defined in s2.3 are referred to in s2.2.
>>> 
> Great.   Thinking again about this.. perhaps 'should only be used' ought to be 'MUST only be used'?
>> 
> The default method and level of canonicalization for URLs (especially for $ref) still needs to be specified. I suspect (RFC 3986, section 6.2.x, where the 'x' is between 1 and 4 according to what you consider appropriate.)
>>> 
> I noticed that making externalId OPTIONAL probably conflicts with the 'MUST be included' statement in para 1 of s3.1.
> It might be clearer to say that they are all REQUIRED (or otherwise) assuming that is what is meant by 'MUST be included'.
> It isn't clear whether this MUST statement applies to the sub-attributes in 'meta' - and if it does there may be a conflict.
>>> 
> The default format definition.. but it still needs a canonicalization mechanism (see comment above for s2.3, $ref)
>>> 
> OK.. we have multiple values... so shouldn't this move to the Multi-valued Attributes section (s4.1.2)?
> The cross reference would probably be better on the top level item 'bulk' rather than on the 'supported' sub-attribute.
>>> 
> There are a couple of examples of '"$ref": "/Groups...."' and '"$ref": "/Users.."' in s8.3; '"endpoint":  "/Users"' and '"endpoint":  "/Groups"' in s8.6;  and in the definition of endpoint in s1.2 there is "/Schemas" which all ought to be relative URLs.
>>> 
> Ok.. but, I suggested providing a definition for 'tenant' back in s3.1.  The updated draft removed 'tenant' from s3.1 rather than providing a definition, so the original comment now applies to the first bullet of s9.3.
>>> 
> Adding the URL would be helpful (<ref... target="http://www.iana.org/time-zones"> if using xml2rfc)
> 
>

---

From: "Morteza Ansari (moransar)" <[email-masked]>
Date: Wed, 6 May 2015 16:55:12 +0000

I believe the telechat review is scheduled for 14th. I think we should try
and publish an updated version of both docs with all the known/agreed upon
issues addressed by end of the week. Hopefully that would help the review
and make it clear what exactly is the state of the doc.

Cheers,
Morteza

On 5/6/15, 9:42 AM, "Phil Hunt" <[email-masked]> wrote:

>Yes I agree with your comment re internationalization. I would think a
>best practice would be very helpful to move the industry.  I guess as a
>provisioning spec we are stuck having to deal with ossification since we
>have to map legacy anglo structures.
>
>>> Note, if I have not commented below, please assume I agree with your
>>>comment and will update the draft to include your feedback.
>>> 
>>>> Summary: Not ready.  The 'major' issue identified is really political
>>>>rather than strictly technical although the proposed syntax does limit
>>>>the applicability (or at least the easy applicability) of the scheme.
>>>>Making the schemas more aware of practice outside the basic English
>>>>speaking world should be an aim of IETF work, IMO.  The minor issues
>>>>are mostly  only just more than editorial nits - and there are quite a
>>>>few of these also.
>>>> 
>>>> Major issues:
>>>> ===========
>>>> collection of name sub-attribute terms are North
>>>>American/UK/Aussie/NZ English -speaking biased.  The authors might
>>>>wish to consider
>>>>http://www.w3.org/International/questions/qa-personal-names.
>>> [PH] I am not sure I agree with your conclusion. SCIM is a
>>>provisioning protocol and not a rendering protocol. SCIM is concerned
>>>with conveying information between systems based on commonly used
>>>fields. Further for formatted name, there is no restriction on how the
>>>name may be structured. Essentially SCIM already follows the above
>>>reference. Note that we don¹t use a regional identifier in name, but
>>>rather have it as a separate attribute ³locale². This enables a UI to
>>>render the name in the appropriate regional method.
>>> 
>>> I believe that what is being reflected is that while database
>>>structures and schemas tend to be ³western² oriented, there are well
>>>trodden industry practices to map those fields to render user facing
>>>material in the proper localized forms.
>>> 
>>> In deference to your concern over the weekend, I re-raised the issue
>>>with Oracle developers and have been informed that there has been an
>>>internationalization review and the specification does not present any
>>>problems for us as international implementers.
>>> 
>>>> To a lesser extent this also applies to the definition of the
>>>>addresses attribute in s4.1.2.  The issue of the representation of
>>>>postal addresses incorporated in I-Ds and RFCs in the xml2rfc schema
>>>>has been debated at length on the rfc-interest mailing list.  The new
>>>>(v3) vocabulary replaces the specific sub-attributes with an ordered
>>>>list of "postalLine" elements (see
>>>>https://tools.ietf.org/html/draft-hoffman-xml2rfc-16#section-2.39).
>>>>Further, the use of country codes in RFCs has been dropped some time
>>>>ago.  It might be better to represent the address in a less specific
>>>>way and leave display up to user interfaces that can consider the
>>>>relevant locale.  My suggestion, FWIW, would be to have a country,
>>>>possibly a code field plus an ordered array of postalLines that can
>>>>contain any of the additional components and cater for any locale
>>>>specific format.
>>> [PH] The suggested workaround of following the format for XML2RFC
>>>using an array of ³postalLine² values causes more problems in the
>>>current SCIM model:
>>> 1.  SCIM does not support array references (e.g. postalLine/1,
>>>postalLine/2). In some cases, the order of elements may not be
>>>guaranteed by some impelementers (e.g. those building on top of LDAP)
>>> 2.  SCIM¹s objective is to provision. So the meaning associated with
>>>the field must be well known to map it to the receivers data system. A
>>>system line postalLine1, postalLine2 would require attribute parsing
>>>which is substantially more complex and unreliable given the wide
>>>variance.
>>> 3.  In practice, international data is collected through a
>>>user-interface which then categorizes the input and maps them to the
>>>appropriate attributes.  If we introduce agnostic attribute naming in
>>>the protocol (postalAddress1, 2 etc) we actually lose knowledge of what
>>>the intended content is.  This means that it becomes impractical to say
>>>does postalAddress2 map to city, county, district, or mail stop of a
>>>target system.
>>> 
>>> IOW. In the XML2RFC, we depend on human editors to validate and align
>>>the data. As a protocol we do not have this luxury.
>>>> Reference to SCIM Protocol document:  At a bare minimum a normative
>>>>reference to the SCIM protocol document (currently
>>>>draft-ietf-scim-api-16) is needed in s1.2 where the protocol is
>>>>referred to in the first two definitions.  In my opinion, this
>>>>document would be improved by the addition of a brief overview of the
>>>>operation of the SCIM protocol and the implications for the design of
>>>>the schema.   For example, s2 talks about 'replacement of a resource':
>>>> Knowing in advance that one of the operations anticipated in the
>>>>protocol is replacement makes this clearer.
>>> No objection. There has been a practical problem that XML2RFC won¹t
>>>let you reference a draft version that does not exist. In practice
>>>we¹ve had to publish API 2 days after core-schema in order to allow the
>>>validation to succeed.  I will amend the document and leave notes for
>>>the RFC editor to co-publish the specs since they reference each other.
>>>> s1.1, Use of OPTIONAL and REQUIRED:  These terms are overloaded in
>>>>this document.  The majority of uses are not specifying features of
>>>>the protocol as per RFC 2119 but indicating the necessity or otherwise
>>>>of the presence of particular attributes in resource types.  AFAICS
>>>>the only RFC 2119 usages are one place in  s2.2.7 for OPTIONAL  and
>>>>two adjacent places in s10.3.1 for REQUIRED .   To avoid the
>>>>overloading it would be easy to omit OPTIONAL and REQUIRED from the
>>>>RFC 2119 list, use the alternative RFC 2119 terminology (MAY in s2.2.7
>>>>and MUST in s10.3.1) and provide a separate note on the usage of
>>>>OPTIONAL and REQUIRED in s1.1.
>>> [PH] In the context of a schema document, the use of OPTIONAL and
>>>REQUIRED is equivalent to protocol normative language and was intended.
>>> 
>>>> (1)   "Attribute names SHOULD be camel-cased":  AFAICS this has no
>>>>impact on the specification or protocol.  My guess is that the
>>>>specification has adopted the convention normally used in JavaScript.
>>>>This is merely a representation of the convention used in SCIM schemas
>>>>and RFC 2119 language is inappropriate.  I suggest replacing this with
>>>> (2) "nameChar   = "-" / "_" / DIGIT / ALPHA": Given the close
>>>>association with JavaScript, it seems inappropriate to allow hyphen
>>>>(-) as a character in attribute names as this is illegal in JavaScript.
>>>> (3) The definition should say whether attribute names are case
>>>>sensitive

---

From: Elwyn Davies <[email-masked]>
Date: Thu, 07 May 2015 18:02:33 +0100

Hi, Phil.

In my last email I realized I left in something about a further email I 
was going to send.  This was due to my thinking the telechat was sooner 
than it actually is.

In creating this email, I realized that I wasn't sure whether the set of 
pre-defined sub-attributes in s2.4 (for the individual values of 
multi-valued complex-type attributes) should also apply to a single 
complex valued attribute.

But the main point was about canonicalization.

In the previous email, I had:

>>> seems to imply that the possible canonicalValues mentioned in the definitions of User, Group etc.
>>> schemas earlier in the draft are actually normative minimum requirements that could, at least in
 >>> some cases, be extended.  The wording used in the earlier sections 
is rather less definitive and
>>> appears to indicate that the suggested values are examples that a service provider might possible
 >>>want to replace if they considered alternative values better suited 
to their application, e.g.
>>> The wording used in the earlier sections seems to need 'tightening up'to make it clear what minimum set of canonicalValues is required for conformance, if indeed that is what is wanted.
>> [PH] Agreed. Suggestion:
>>
>> A collection of suggested values for an attribute. For example often used with the “type” attribute to categorize a value such as “home” or “work”.  The service providerMAY choose to ignore values it does not support.
> This helps.  The wording in s4.1.2 needs a little more work (see other email)....
[So here it is]

Is it intended that the various canonical values of the "type" 
sub-attribute for emails, etc., stated in s4.1.2 are normative 
requirements?

It seems possible that there is a subtle difference between the "ims" 
and "photos" cases and the others:  For the "ims" and "photos" cases a 
different canonicalization is or might be needed for each possible type 
values, in which case the values would have to be tied down and be made 
normative, whereas the others are just a convenience for human users 
that would not generally be interpreted by machines with the same 
canonicalization whatever the value of "type".  OTOH, having 
standardized values helps the internationalization of the user interface 
in clients.

If so I would suggest that these are rephrased to make it clear, for 
example, for emails (and similarly for phoneNumbers and addresses):
OLD:
       The "type" sub-attribute of contains values of "work", "home", and
       "other", and MAY allow more types to be defined by the SCIM
       clients.
NEW:
       The "type" sub-attribute is used to provide a classification
       meaningful to the (human) user.  The user interface should
       encourage the use of basic values of "work", "home",
       and "other", and MAY allow additional type values to be used
       at the discretion of the SCIM clients.

For "ims" (and similarly for "photos"):
OLD:
       The "type"
       attribute defines several "canonicalValues" to represent currently
       popular IM services: "aim", "gtalk", "icq", "xmpp", "msn",
       "skype", "qq", "yahoo", and "other".
NEW:
       The "type" sub-attribute SHOULD take one of the following
       values: "aim", "gtalk", "icq", "xmpp", "msn", "skype", "qq",
       "yahoo", and "other", representing currently popular IM services
       at the time of writing. Service providers MAY add further values
       if new IM services are introduced and MAY specify more detailed
       canonicalization rules for each possible value.

Regards,
Elwyn

---

From: Phil Hunt <[email-masked]>
Date: Thu, 7 May 2015 10:12:49 -0700

Elwyn,

Thanks for this. I think these changes are reasonable and strike a better balance on standardized canonicalization vs. providing allowance for discretion.

I will add to the next update. 

Phil

[email-masked]

> On May 7, 2015, at 10:02 AM, Elwyn Davies <[email-masked]> wrote:
> 
> Hi, Phil.
> 
> In my last email I realized I left in something about a further email I was going to send.  This was due to my thinking the telechat was sooner than it actually is.
> 
> In creating this email, I realized that I wasn't sure whether the set of pre-defined sub-attributes in s2.4 (for the individual values of multi-valued complex-type attributes) should also apply to a single complex valued attribute.
> 
> >>> some cases, be extended.  The wording used in the earlier sections is rather less definitive and
> >>>want to replace if they considered alternative values better suited to their application, e.g.
>>>>>   userType
> Is it intended that the various canonical values of the "type" sub-attribute for emails, etc., stated in s4.1.2 are normative requirements?
> 
> It seems possible that there is a subtle difference between the "ims" and "photos" cases and the others:  For the "ims" and "photos" cases a different canonicalization is or might be needed for each possible type values, in which case the values would have to be tied down and be made normative, whereas the others are just a convenience for human users that would not generally be interpreted by machines with the same canonicalization whatever the value of "type".  OTOH, having standardized values helps the internationalization of the user interface in clients.
> 
> If so I would suggest that these are rephrased to make it clear, for example, for emails (and similarly for phoneNumbers and addresses):
> OLD:

---

From: Elwyn Davies <[email-masked]>
Date: Thu, 07 May 2015 18:16:25 +0100

Phil,

Thanks for the response... I can't say that the text as supplied is 
quite right - please apply further edits if you and your co-authors 
intended otherwise!

Cheers,
E.

---

From: Phil Hunt <[email-masked]>
Date: Fri, 8 May 2015 23:07:56 -0700

> It isn't clear whether this MUST statement applies to the sub-attributes in 'meta' - and if it does there may be a conflict.
Re-reading the section I see the issue. The first paragraph is intending to say the attributes “id” and “meta” and “externalid” must be defined (as in the schema for an object) for every scim resource.  In contrast, the paragraphs below indicate if a value is required or not.

I will add some clarifying text and try to correct the confusion.

Phil

> On May 6, 2015, at 9:18 AM, Elwyn Davies <[email-masked]> wrote:
> 
> Hi, Phil.
> 

Phil

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