Subject: [Gen-art] review of draft-ietf-scim-api-16.txt

From: Francis Dupont <[email-masked]>
Date: Wed, 22 Apr 2015 17:06:07 +0200

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-api-16.txt
Reviewer: Francis Dupont
Review Date: 20150418
IETF LC End Date: 20150420
IESG Telechat date: unknown

Summary: Ready with nits

Major issues: None

Minor issues: None

Nits/editorial comments: many!
 - Abstract page 1: a standardized services:
  either 'a standardized service' or 'standardized services'

 - Abstract page 1: add at least a comma in:
   a common user
   schema and extension model and a service protocol
                             ^ e.g., here

 - ToC page 2:
   3.4.1.  Retrieving a known Resource
                        ^ Known

 - about keywords: IMHO it is far better, less ambigous and BTW
  compliant to avoid lower case keywords.

 - 1.1 page 4: some examples of (not very ambigous) lower case "may"s.

 - 3.2 page 6: ask the RFC Editor to check the page break is not
  as badly placed as in my paper copy (PATCH alone at last line).

 - 3.2 page 7 table 1 and a lot of other places: e.g. -> e.g.,

 - 3.5.2 page 30: long uri cut issue (there is no perfect solution:
  either cut it into two lines, or insert a line break. But you
  should be consistent in this choice).

 - 3.5.2 page 31: misplaced comma?
    a patch operation that sets a value's
   "primary" attribute to "true", SHALL cause the server to
                                ^

 - 3.5.2 page 31: no closing parenthesis:
    resource (subject to
             ^

 - 3.5.2.2 page 35: missing required SP:
    "path":"members[value eq\"2819c223...919d-413861904646\"]"
                            ^

 - 3.5.2.3 page 38: selction -> selection

 - 3.6 page 42: from my long list a debatable lower case "should not":
   the previously deleted resource should not fail

 - 3.9 page 60: why an upper case "OR" in:
   "attributes" OR
   "excludedAtributes"

 - 3.10 page 61: "A" in plurals?
   A Complex
   attributes' Sub-Attributes are referenced

 - 5 page 70: bad wording:
   To increase the likelihood that the input and comparison of unicode
   usernames and passwords will work in ways that make sense for typical
   users throughout the world there are special string preparation and
   comparison methods (PRECIS) that MUST be followed for usernames and
   passwords.

 - 7.2 page 73: spurious comma:
   As mentioned in ,Section
                   ^

 - 7.4 page 74: i.e. -> i.e., (the only one I found :-)

 - 9.2 page 78: strange ', .'s (missing parameter in a macro?)
   [OpenSearch]
              Clinton, D., "OpenSearch Protocol 1.1, Draft 5", .

   [Order-Operations]
              Wikipedia, "Order of Operations: Programming Languages", .

Regards

[email-masked]

---

From: Phil Hunt <[email-masked]>
Date: Wed, 22 Apr 2015 08:23:08 -0700

Francis,

Thanks for your detailed review. Much appreciated!

I will revise the document as suggested in the coming week. 

Thanks!

Phil Hunt

> On Apr 22, 2015, at 08:06, Francis Dupont <[email-masked]> wrote:
>

---

From: Phil Hunt <[email-masked]>
Date: Fri, 24 Apr 2015 13:57:25 -0700

Francis,

Thanks again for the detailed review. 

Comments inline. If no comments, the changes have been made to the draft posted moments ago.

I believe this should address all of your comments.

Best regards,

Phil

[email-masked]

> On Apr 22, 2015, at 8:06 AM, Francis Dupont <[email-masked]> wrote:
> 
Tried to make more consistent.  Note: I prioritized trying to maintain alignment with some “id” shortening using “…". When line is still too long, I fail back to putting the value on the beginning of the next line.

I’ve tried to achieve a balance here, but am open to making further changes to meet IETF “style” where needed.
>   "primary" attribute to "true", SHALL cause the server to
The section was a bit awkward. Rephrased.

>    "path":"members[value eq\"2819c223...919d-413861904646\”]"

The example appears to be valid. There is no SP between members and [
>   “excludedAtributes"

Corrected multiple cases.
>   comparison methods (PRECIS) that MUST be followed for usernames and

The text comes directly from the introduction of SASLPREPBIS.