[occi-wg] Consolidated list of editorial changes from issues list

[Gary Mazz]

Hi,

This is a consolidated list of editorial changes originated in the 0cci issues list found on http://code.google.com/p/occi/issues/list

This list is to act as a guide for occi-wg editors writing the occi specification.

This list attempts to place the recommendations in sequence in the document.

cheers,
gary

================================================================================
Section: Overall

***Comment:*

  - move table of contents after abstract

  - use MUST, SHOULD, MAY, CAN...  should be uppercase

  - "Each implementation has a single OCCI end-point URL"
    should be 'each deployment' or 'each service'?

  - TIP, WARNING: are they normative?   Like, the tip after Par. 54
    contains a SHOULD.  But I am asking about tips in general, not
    about this particular one.

  - "A simple peer review process is available for extending the 
    registries"
    That process is not described, not referenced.

  - "This scalable approach..."  
    not relevant, really - can go into footnote


Section: Document-wide

  1. The character set use in communications should be specified

  2. Header Capitalisation of "OCCI working group" -> "OCCI Working Group"

  4. Lacking/Inconsistent normatives throughout

  5. What is the minimum set of requirements/features (a profile) that
needs to be implemented so that one is OCCI compliant?

  6. Format of references - should be enclosed by '[' and ']' e.g. [REF22 <http://code.google.com/p/occi/source/detail?r=EF22>]

  7. Use appropriate page breaks

  8. Revise use of round bracketing

  9. Ensure consistency of dot or dash attribute notation in all examples

  10. There is no consideration in the spec for the states that a resource
can have

  11. All extensions should be placed and grouped under a Section named
"Extensions"

  12. Aspects of security are dealt with in 3.3.1 and 3.7. It would be
better for these to be placed together for context and ease of reading.

  13. For numerical attributes it might be useful to state their numerical
base e.g. if these should be Base-2 or Base-10.

  14. Would be useful to introduce the notion of OCCI extensions in the
walk through.

====================================================================================


Section: abstract

*Paragraph:*

Comment: first sentence should move to --> status; 'note' in walkthrough is
misleading...


=====================================================================================
Section: OCCI Core
Pages: 5-14

41. P13 "Collection" link relation
    1. Is a self-referiental reference appropriate?

  1. Paragraph 26 "A "Resource Oriented Architecture (ROA)""
      * Supply reference


  2. P26 "Each resource (identified by a canonical URL)"
    1. Bracket usage - suggestion "Each resource, identified by a canonical
URL,

  3. P26 "has zero or more representations"
    1. If a resource has no representation then to all intents it does not
exist within the system. Suggest "1 or more"

  4. P26 "Metadata including associations between resources is exposed via
HTTP headers (e.g. the Link: header), except in the case of collections
where Atom is used as the meta- model."
    1. Which is normative? Are there other ways?

  5. P26 Comment
    1. Is the supplied tip of relevance in the context? If so give an
example to explain.

  6. P27 "The interface"
    1. What interface? Also the interface is defined in _part_ by the URL -
consider rephrasing this paragraph

  7. P27 "in-band/out-of-band"
    1. Easier to supply a definition of this here and then later in the doc
refer to the definition in glossary. Better way to introduce the concept to
"newbies".

  8. P28 "HATEOAS"
    1. Expand the acronynm

  9. P29 "WebDAV definitions are used for MOVE and COPY"
    1. COPY is a valid operation on the external interface of an
infrastructure provider. MOVE however is not and something that might be
implemented optionally. Suggest to have MOVE as an extension and not part
of core. Motivation not obvious to have in core.

  10. P29 Comment
    1. I can PUT to create and POST to update - would be worth explaining
which to use (normative)

  11. P29 "DELETE" - "and everything "under" it"
    1. Better worded as "and all it's child resources" Lars pointed this
out also

  12. Section 3.3.1 Authentication
    1. Needs to be extensible and adaptable - might consider it part of
OCCI extensions also? E.g. SAML support

  13. P33 Comment
    1. An example should be given

  14. P34 Comment
    1. Ever seen a working model that did not include links between entities?

  15. P34 "without regard to how they interrelate."
    1. Surely this should be "with regard to how they interrelate." Both
meta-model and model define links in general

  16. P34 "the objects"
    1. change to "infrastructure resources (objects)"

  17. P36 "http://purl.org/occi/kind/ namespace"
    1. Who controls this?

  18. P36 Comment - "Warning"
    1. These are repeated through out - rather than warn, insert a section
on how to extend the specification including a note on this warning, how
the peer process works etc. Then refer to the section from various parts of
the doc

  19. P37 "Internet media types"
    1. Better to call this "Internet MIME types"?

  20. P39 "dash character (“-”)"
    1. Why the dash over the dot? Where's the motivation, reason is a
little unclear. If all representations are UTF8 compliant then should this
matter?

  21. P40 Warning is repeated
    1. Repeated: Use a dedicated section on extending OCCI and ref to it

  22. Table 1 "Common Attributes"
    1. "OCCI-Updated" - is the HTTP "Last-Modified" header sufficient?
    2. Normative - are all these to be supported?

  23. P43 Comment
    1. It is noted that a list of actions are available - where? There's
none in the spec doc

  24. P34 Warning
    1. Repeated: Use a dedicated section on extending OCCI and ref to it

  25. P44 "An action is triggered via an HTTP POST"
    1. Normative and possibly give the reason as to why POST is used.

  26. P46 Tip
    1. Usefulness of this in the context?

  27. P47 Tip
    1. Usefulness of this in the context?

  28. P48 "The meta-model defines how objects interrelate."
    1. Not a normative definition. Some include: http://bit.ly/gwCA5
Consider revising.

  29. Section 3.5.1
    1. What happened to the useful OCCI-text examples of categories?

  30. P51 Tip
    1. More than just a tip. This is a feature (tagging via categories)
that Atom gives for free. Suggest making it a paragraph.

  32. P53 Tip "O(n+1)"
    1. Should this not be O(n^2)? - for every resource rendering (1
operation) there is the rendering of its details (1 operation). Therefore
in a list of 4 resources we have to perform a constant 2 operations per
resource, hence n^2 operations.

  33. P55 Comment on examples
    1. Should the example show the encoded ';' character?

  34. Section 3.5.3
    1. What happened to the useful OCCI-text examples of linking?

  35. Table 2
    1. What are the normative?
    2. "help" - appropriate and useful in core section?
    3. "icon" - appropriate and useful in core section?

  36. P58 "public peer review"
    1. Point to an extension section detailing this process

  37. Section 3.6.1 Comment
    1. Explain what "foreign markup" is

  38. P59 Comment
    1. Example needed

  39. Section 3.8 "Registration" Comment
    1. Place in an appendix


Page 10, paragraph 52

"Where an operation returns multiple resources ..." to be replaced with
"Where an operation COULD return multiple resources..."

to make it clear that a collection is always returned, even if there is a
single result.

==========================================================================================
Infrastructure:

  1. Table 3
    1. Suggest to move it after introducing kinds - better logical flow


  2. P77 "Cloud infrastructure can be modeled using three primary kinds:
compute, network and storage."
    1. Rephrase to: "Cloud infrastructure can be modeled using the
following three primary kinds:"

  3. Table 4 "Recorded information resources"
    1. reword to "Information recording resources"

  4. Table 5
    1. Suggest to include boot volume attribute (Richard)
    2. "Enum (standard, checksum)" -> "Enum (none, checksum)"
    3. How to extend enumerations? Should we just use text field instead?

  5. Section 8.1.2 Comment
    1. These are mostly network client attributes. Are they sufficient to
model a pool of static IPs?

  6. Table 6
    1. OCCI-Network-Address - unclear description - is it a gateway IP or
node IP address?
    2. OCCI-Network-Allocation - how is manual allocation performed, by who?

  1. Section 9
    1. What is the relevance of the date?

  2. P83 OpenSearch
    1. Give example for context/relevance

  4. Section 10 "OCCI Status Extension"
    1. Better named as "OCCI Task Reporting", especially as there's the
"OCCI Tasks Extension"?
    2. Isn't this extension just a specialisation of Monitoring (Lars noted
this too) and should be reflected as such?
    3. Very much related to the "OCCI Task Extension" - is it better combined?
    4. An example of the extensions usage would be helpful

  5. Table 8
    1. Uses dot notation for attribute naming - consistency
  
  7. Section 11
    1. What is the relevance of the date?
    2. An example of the extensions usage would be helpful

  8. Table 9
    1. Uses dot notation for attribute naming - consistency

  10. Section 12 "OCCI Registries"
    1. What are the normative HTTP status codes?

  11. Table 11
    1. We should also mention mailing list contributors as this IS a
community effort and not just that of a few.

==============================================================================
 7. Bibliography
    1. Move to a dedicated section at the end of the whole document
  40. Page 13 Bibliography
    1. Move to a dedicated section at the end of the whole document
 
  3. Section 9 Bibliography
    1. Move to a dedicated section at the end of the whole document
    2. What is the relevance of the date?
  6. Section 10 Bibliography
    1. Move to a dedicated section at the end of the whole document
  9. Section 11 Bibliography
    1. Move to a dedicated section at the end of the whole document