Hi, 

The following is my comments on the 2005-09-13 draft of the Deployment API.
The comment format is similar to the Aardvark Comment Format described in the
following page:

http://www.opengroup.org/austin/aardvark/format.html


@ page 10 section 3.4.3.3 Extra deployment options

Problem:
  In the 1st item of the bullet list, the following sentence:

    Every option is named by a URI.

  does not contain RFC2119 keyword.

To fix:
  Change the sentence as follows:

    Every option MUST be named by a URI.

@ page 10 section 3.4.3.3 Extra deployment options

Problem:
  In the 7th item of the bullet list, the following sentence:

    Options MAY be processed in any order.

  "MAY" is inappropriate in a list of requirements.

To fix:
  Use "may" instead of "MAY" and change the order of the sentences,
  as follows:

    Options MUST NOT require a specific order of processing.  Options
    may be processed in any order.

@ page 11 section 3.5 WS-DM Integration

Problem:
  The 2nd sentence of the 1sst paragraph says:

    Both Portal and System endpoints support the MUWS ResourceId and
    ManageabilityCapability attributes ...

  It is unclear whether it is a requirement or not.

To fix:

  If it is a requirement, use "MUST", such as:

    Both Portal and System endpoints MUST support ...

@ page 13 section 4.2.2 Portal Endpoint Operations

Problem:
  In the description of the "Create" operation, the following sentence:

    hostname is OPTIONAL.

  is inappropriate because the "OPTIONAL" in RFC2119 keyword means that
  "an implementation can choose whether to implement the feature or not".
  An optional parameter is not "OPTIONAL" in RFC2119's sense.

To fix:
  Change the sentence to:

    hostname is optional.

@ page 13 section 4.2.2 Portal Endpoint Operations
here and also at
page 15 section 4.3.2 System Endpoint Operations

Problem:
  Typo.  The operation name "GetResourceProperties" should be "GetResourceProperty".

To fix:
  Change "GetResourceProperties" to "GetResourceProperty".

@ page 14 section 4.3.1 System Endpoint Properties

Problem:
  The "Meaning" column of the property "api:StartedTime" says "Time system was
  *terminated*."  Is it intentional?

To fix:
  If the property indicates "started" time, say so.

  BTW, when a system is "started"?  After receiving "Initialize" message, or
  "Run" message, or otherwise?  The word "started" must also be clarified.

@ page 19 section 6.2.1 AddFile

Problem:
  In the AddFile operation, the word "schema" is used to indicate the first
  part of the URL/URI (e.g. "http" in "http://www.example.com/").  However,
  RFCs defining URL/URI format (RFC1738 and RFC2396) uses the word "scheme"
  for that part.

To fix:
  Change "schema" to "scheme".

@ page 22 section 6.2.7 Destroy

Problem:
  In the 2nd paragraph, "MAY NOT" is used.  However, in RFC2119, "MAY NOT"
  is undefined and its use is confusing to the readers.
  You may not use "MAY NOT".

  In general, "MAY" means "allowed to do".  Negation of "MAY" ("MAY NOT") will
  mean "not allowed (prohibited)" but such a sense is properly indicated by the
  use of "MUST NOT".  If you want to say "allowed not to do", "need not" or
  "not required to do" will work.

  In this specific case, "MAY" is used to indicate *possibility*.  However,
  "MAY" in RFC2119 only indicates *permission* to implementations.
  In such a case lowercase "may" may be appropriate.

To fix:
  Change "as it MAY NOT be valid" to "as it may be invalid".

[END]