[apps-discuss] apps-team review of draft-cdmi-mediatypes-04

[Barry Leiba <[e-mail]>]

I have been selected as the Applications Area Review Team reviewer for
this draft (for background on apps-review, please see
http://www.apps.ietf.org/content/applications-area-review-team)
Please resolve these comments along with any other Last Call comments
you may receive. Please wait for direction from your document shepherd
or AD before posting a new version of the draft.

Summary: The draft is pretty much ready to go, but there are quite a
few minor items that really should be fixed.  There's a pervasive
number-agreement problem.  Remember that "a set of X" is *singular*,
even if there are many X, because the subject is "a set", not "50 X".
If that's not what you want, you need to re-word.

No major issues.

Minor issues:

3.1, number agreement error
OLD
   A CDMI object is the basic storage element in a CDMI system and are
   analogous to files within a filesystem.
NEW
   A CDMI object is the basic storage element in a CDMI system and is
   analogous to a file within a filesystem.

3.1, JSON reference
It seems odd to me to have a general reference to the JSON web site,
followed immediately by a proper reference to the RFC that defines the
format.  I see no reason for the reference to the web site.
Alternatively, if you want to cite the web site, maybe putting it
inline would be better, like this:

   The object is represented in the CDMI interface in JSON
   format [RFC4627] (see the JSON web site at http://www.json.org/
   for general information about JSON).

3.1, number agreement error
OLD
   defines the JSON format.  Each data object has a set of well-defined
   fields that include a single value and optional metadata.

NEW, if the subject is "set"
   defines the JSON format.  Each data object has a set of well-defined
   fields that includes a single value and optional metadata.

NEW, if the subject is "a field"
   defines the JSON format.  Each data object has a set of well-defined
   fields; each field includes a single value and optional metadata.

3.1, normative language ?
OLD
   but the application/cdmi-object should be represented in the CDMI
   interface as defined in section 8 of the CDMI specification.
NEW
   but the application/cdmi-object SHOULD be represented in the CDMI
   interface as defined in section 8 of the CDMI specification.

3.2, number agreement error
OLD
   Container objects are the fundamental grouping of stored data within
   CDMI and is analogous to directories within a filesystem.
NEW
   A container object is the fundamental grouping of stored data within
   CDMI and is analogous to a directory within a filesystem.

3.2, number agreement error
OLD
   Each
   container has zero or more child objects and a set of well-defined
   fields that include standardized and optional metadata.
NEW
   Each
   container has zero or more child objects and a set of well-defined
   fields that includes standardized and optional metadata.

(Consider whether "includes" should be "represents".)

3.2, normative language ?
OLD
   implementations are free to represent the container in amy form they
   choose, but the application/cdmi-container should be represented in
   the CDMI interface as defined in section 9 of the CDMI specification.
NEW
   implementations are free to represent the container in amy form they
   choose, but the application/cdmi-container SHOULD be represented in
   the CDMI interface as defined in section 9 of the CDMI specification.

3.4, number agreement error
OLD
   Capability objects are a special class of container object that allow
   a CDMI client to discover what subset of the CDMI standard is
   implemented by a CDMI provider.
NEW
   Capability objects form a special class of container object that
   allows a CDMI client to discover what subset of the CDMI standard
   is implemented by a CDMI provider.

3.4, number agreement error
OLD
   For each URI in a CDMI system, the
   set of interactions that the system is capable of performing against
   that URI are described by the presence of named "capabilities".
NEW
   For each URI in a CDMI system, the
   set of interactions that the system is capable of performing against
   that URI is described by the presence of named "capabilities".


3.5, dangling subject error
OLD
   If
   supported by the cloud storage system, cloud clients create the queue
   objects by using the same mechanism used to create data objects.
NEW
   If queues are
   supported by the cloud storage system, cloud clients create the queue
   objects by using the same mechanism used to create data objects.

4, definition of "transport protocols"
I have a bit of a problem, in general, with referring to HTTP and SMTP
as "transports"; they are application protocols that sit above the
transport layer, and they, themselves, use transport protocols such as
TCP (and there's an experiment doing HTTP over SCTP).  Maybe I'm alone
in this concern, but I'd rather avoid that terminology.  I also don't
really see a need to mention SMTP (and not, say, BEEP or whatever).
Why not this?:
OLD
   The CDMI uses HTTP (RFC 2616) transport and does not make sense
   outside the HTTP realm.  We do not expect the CDMI to use other
   transports like SMTP (RFC2821) or raw TCP (RFC 793) protocols.
NEW
   The CDMI operates over HTTP (RFC 2616) and does not make sense
   outside the HTTP realm.  We do not expect the CDMI to operate
   over other protocols, nor to use a transport protocol, such as
   TCP (RFC 793), directly.

6.1: You don't need to capitalize "confidentiality" in the first sentence.

6.1, I suggest this change:
OLD
   CDMI does not
   contain any specific mechanisms and relies on transport mechanisms
   like https [RFC2818] for confidentiality and integrity of the
   messages across the network.
NEW
   CDMI does not
   contain any specific mechanisms for this, and relies on mechanisms
   such as TLS (see https [RFC2818]) for confidentiality and integrity
   of the messages across the network.

I'm also wondering whether 2818 should be a normative reference,
rather than informative.  I'm on the fence....

6.2, missing comma; I had to read this three times to understand it.
OLD
   If required applications should use appropriate URL
   authentication and authorization techniques.
NEW
   If required, applications should use appropriate URL
   authentication and authorization techniques.

(In the next sentence, "fine-grained" should be hyphenated.)

6.3; what does "to facilitate the access" mean?  Please reword.

6.4; hyphen, commas, number agreement
OLD
   JSON related security considerations described in RFC 4627 [RFC4627]
   applies.
NEW
   JSON-related security considerations, described in RFC 4627 [RFC4627],
   apply.

7; a comma after "Faltstrom" would make this easier to understand.

-- 
Barry Leiba