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@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@sun.com D-93049 Regensburg http://www.sun.com