[occi-wg] Consolidated list of editorial changes from issues list
Thijs Metsch
Thijs.Metsch at Sun.COM
Thu Oct 8 14:43:26 CDT 2009
Hi all,
Find a fresh draft attached. reflecting changeset 55...
Cheers,
-Thijs
On Thu, 2009-10-08 at 08:37 -0600, Gary Mazz wrote:
> 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
>
>
>
>
>
>
>
>
>
>
>
> _______________________________________________
> occi-wg mailing list
> occi-wg at ogf.org
> http://www.ogf.org/mailman/listinfo/occi-wg
--
Thijs Metsch Tel: +49 (0)941 3075-122 (x60122)
http://blogs.sun.com/intheclouds
http://www.twitter.com/befreax
Software Engineer Cloud, Grid and Virtualization
Sun Microsystems GmbH
Dr.-Leo-Ritter-Str. 7 mailto:thijs.metsch at sun.com
D-93049 Regensburg http://www.sun.com
-------------- next part --------------
A non-text attachment was scrubbed...
Name: occi-specification.pdf
Type: application/pdf
Size: 84542 bytes
Desc: not available
Url : http://www.ogf.org/pipermail/occi-wg/attachments/20091008/8ebd686a/attachment.pdf
More information about the occi-wg
mailing list