Hi Sergio, On Tuesday 13 May 2008 03:26:04 Sergio Andreozzi wrote:
This is the official Working Group last call for GLUE 2.0 and we invite all of you to read the specification and to send your feedback by Friday, 12 AM CEST.
OK, here are my comments, restricted to comments for the whole document or for the main entities and Appendix A and B. Of course, feel free to ignore these suggestions. (when suggesting changes to text, I've used the following convention: "[aa]" means delete "aa", "/bb/" means add "bb", "/bb/[aa]" means replace "aa" with "bb") *** General comments (not page specific) Top left corner of each page has "GWD-R, GWD-I or GWD-C"; this is not consistent throughout the document. Bottom left corner of each page (except title page) has what looks like an email address. This is not consistent throughout the document. Top right corner of each page (except title page) has a date. This is not consistent throughout the document (contents pages vs document main-body). The RFC-2119 references (MAY, SHOULD, MUST, etc) are not typeset in a uniform fashion. They're capitalised for most part but I believe there's the occasional usage in lower-case (Appendix A has them in lower-case). A search-and-replace should identify all such problems. Could RFC-2119 terms be typeset in a slightly smaller font? I find this helps a surprisingly when dealing with all-caps acronyms and phrases. There are many places where "can" is used instead of an RFC-2119 term. Could you search for all instances of the word "can" and replace (almost) all of them with either "MAY" or "SHOULD"? References are not handled consistently through the document: in some places they are cited using a square-brackets notation ("GLUE Schema 1.x [glue-1x]" ), in other places URIs are placed in-line (e.g., "RFC 2119 (see http://www.ietf.org/rtc/rfc2119.txt)."). A consistent scheme should be used. My vote would be for square brackets. The start of the References section doesn't appear in the Table of Contents. The Appendices are currently referenced as additional numerical sections: Appendix A is Section 16, Appendix B is Section 17. In my experience, it is usual to have Appendices start as a separately "numbered" sections, where the enumeration is expressed in upper-case Alphabet (hence the "A" of Appendix A). Could the two Appendices be altered to follow this convention? Could we have consistent typesetting of the entity names? The capitalisation tends to vary throughout the document: sometimes capitalised, sometimes lower-case (e.g., "UserDomain" vs "userDomain" vs "userdomain" vs "user domain"). It might help when reading the document if the entity names stood out more; for example, they were all in italics. However, this is a style issue, so it's just a mild suggestion. The phrase "this is an abstract entity not meant to be instantiated" is repeated for different abstract entities. This is imprecise: instances of this phrase should be updated so they say that abstract entity "SHOULD NOT be instantiated" or "MUST NOT be instantiated". The OtherInfo property the word "example" should be plural ("examples"), perhaps a better phrase is "[...] are all examples of valid syntax". There are several places where the document repeats information; for example on page 4 it is emphasised that ID is of type URI, where this is clearly stated in the Entity definition. Do we really need to labour this point? Could these statements be replaced by a single blanket statement (in General Comments, for example) that implementors must ensure that they follow the correct types for each entity property. *** Page 1 (title page) Could my association be changed to "DESY" (i.e., all caps) ? Abstract: Some suggestions (feel free to ignore :) "[...] described /using/[in] natural language /and/ enriched with a graphical representation [...]" "As a conceptual model, /it/[this] is /designed to be/[meant to be] /independent of the underlying information system/[implementation-independent]." "Rendering to concrete data models such as XML Schema, LDAP /Schema/, and /SQL/[relational] are provided in [a] separate document/s/." See also changes within first para. of Introduction (page 4). *** Page 4. Introduction, If the abstract is updated, the corresponding sections of the introduction 1st para should have similar changes applied. The terms LDAP, XML Schema and "relational" (perhaps replaced by "SQL") are used without citing references for them. On page 6. there is a reference to "an interoperability profile" without this term being defined. The closest to a definition is the last sentence of the first para of the introduction, which hints towards an interopt. profile. The term "interoperability profile" should be defined somewhere and the introduction seems like a natural place. This could be an additional paragraph, appearing after the first. General Statements Instead of "The ID MUST be compliant with the syntax of a URI.", how about simply "All ID property values must be valid URIs". Assuming ID is moved to Entity, perhaps some of the content of the paragraph about ID and LocalID could be moved to the section in Main Entities, where the "Entity" entity is defined. The terms "URI" and "URN" are used without defining them. A simple citation of the relevant RFCs should be sufficient. I believe SI is "Le Système International d'Unités", not "International System". ISO-2955 might be a more appropriate reference than Wikipedia, although the URI (from Wikipedia) is spectacularly ugly: http://isotc.iso.org/livelink/livelink/fetch/2000/2122/138351/138352/4446951... I feel we should cite some reference for the binary SI prefix, but I'm not sure of the best source to reference. Could we typeset 10^9 and 2^30 correctly: with the exponent numbers in superscript? The "place-holder values" section is either Appendix A or Section 16, not "Appendix 16". I feel we should state whether implementors MUST or SHOULD follow the guidelines in Appendix A, rather than just introducing the Appendix. There's a throw-away comment about "attributes" and "properties" being synonyms. Could we simply replace all instances of "attribute" with "property" and remove this paragraph? *** Page 5 The associations between Domain and Location, and Service and Location are described as "primary located at", this is perhaps better expressed as "primarily located at" or "has primary location". *** Page 6 Do we really want to make CreationTime and Validity properties required? How about these changes to the descriptions: CreationTime: "Timestamp /describing/ when the Entity [...]" Validity: The duration after CreationTime that the information presented in the Entity MAY be considered relevant. After that period has elapsed, the information SHOULD NOT be considered relevant. CreationTime and Validity are not included in the inherited properties in the other entities. Extension: "A key,value pair enabling /the/[to] /association of/[associate] extra information /with/[to] /an Entity/[a class] instance [which is] not capture by the model" Location Longitude: "The position of a place east or west of /the primary meridian (located in/ Greenwich, /UK/[England] /)/." We should also mention that -180 degrees is not a valid meridian of longitude (it's +180 degrees instead). The final para of the page mentions "interoperability profile" without defining this term (see comments about page 4). *** Page 7 Contact: URL property: this name seems wrong. The property is a URI, which is something the description seems to contradict itself over (URL, no URI, ....). Perhaps it should be given a more generic name, although I'm struggling to come up with something better than "transport". Domain: The description reads more like a description of a User-domain: AdminDomain objects (as a subclass of Domain) are not assigned Roles, so this description is wrong. Perhaps the "WWW" property should really be something like "FurtherInfo". The Type is URI, not URL, so could express something other than a web-page. For example, a grid might choose to express Domain further information using gopher, or by looking up the details through the French Minitel system, by querying some database service, or ... *** Page 8 AdminDomain: The description shouldn't use "can", these words should be change to MAY; "should" should be "SHOULD". Distributed Property: "admindomain" --> "AdminDomain" "This structure /MAY/[can be] represent[ed] /a/[via the] "participates in" association." UserDomain: Description: "A collection of actors that /MAY/[can] be assigned [with] user roles and privileges to Service or Share entities via Policy entities." I'm not sure why is there a Level property; isn't this described by the UserDomain--UserDomain hierarchy? *** Page 9 The para describing Virtual Organisations seems a little out of sequence. For example, "VO" is used before it's defined in the second sentence. The term is defined in the third sentence, rather than where "Virtual Organisation" is first used. Someone should spend a little bit of time tidying up that para. The final para should be changed: "This structure /MAY/[can be] represent[ed] /a/[via the] "participates in" association." Service: Capacity property: this is the first time OGSA is used, but it isn't referenced. "StatusPage" should be "StatusInfo" (it isn't necessarily a page). The description says it's a web page. It might not be: it could be via RFC-742 (finger protocol), automated/recorded phone message. *** Page 10 Comma missing after "e.g." in the "The simplest Service [...]" sentence. And the final sentence is imprecise: "Endpoints, Shares, Managers and Resources /MUST/[can] belong to /precisely/[only] one Service." Endpoint: The name "URL" for the property doesn't seem correct: the type is URI and the endpoint might not be a URL. How about something like Target, Contact or just "URI"? WSDL: the description says this is a URL. The Type is URI so the value might not be a URL. SupportProfile The description is useless: it doesn't specify what this is in any way. ImplementationVersion. The description mentions the three-number representation (major-version.minor-version.patch-level) without specifying whether information MAY, SHOULD or MUST use this form. *** Page 11 DowntimeStart description: "The [starting] timestamp /describing when/ [of] the next [scheduled] downtime /is scheduled to start/" (likewise for DowntimeEnd) "For Grid services [...] (see Section 0)." For the JMS example, the phrase "Java Messaging Service" should be capitalised. *** Page 13 Policy: Neither the Scheme or Rule properties appear to be particularly well defined. UserDomain isn't capitalised correctly (last sentence of last para.) *** Page 14 MappingPolicy Default property "user domain" --> "UserDomain" "This entity can be used to express [...]" Is this "MAY be used" or "SHOULD be used" ? [skipping onto Appendices] Appendix A: Some general comments: Various RFCs are mentioned without including references. Could the URI for RFC-2119 be adapted for these other references? Some of the examples appear to be converted to external links within the document; for example, the "www.example.org" example (16.2.1 "Fully qualified domain name") appears in blue text with an underline. Could these be converted back to plain text? There's many references to "unknown value" or similar. I feel these should all be changed to "place-holder value". I've tried to note where the occur, but searching should find them all. The RFC-2119 terms (MAY, SHOULD, etc) are all lower-case *** Page 39 The first place-holder values should be "Simple strings". This is currently body-text rather than Section 16.2.1 *** Page 40 FQDN: Could you update the indentation used for the examples? It appears to be inconsistent with the others. *** Page 41 Integers: "For these reasons, information providers MUST use all-nines to indicate /a place-holder/[an unknown] value." File path: Software should accept either value as /a/[an unknown-value] place-holder /value/." *** Page 42 URI: "Take care with the URI encoding. All /place-holder/[unknown] URI values MUST be [...]" "For "mailto" URIs [...] /Place-holder/[Unknown] mailto /URI values/[URIs] MUST use [...]" *** Page 43 FQAN: "Where VO is well-formed /FQDN/[DNS name]. Unlike /FQDNs/[DNS names], VO names must be lower-case. The [unknown] place-holder value for DQAN is derived from the /place-holder/[unknown] /FQDN/[DNS name] (see /section 16.2.x/[above])." Geographical location: "(0,0) MUST be used to specify /a place-holder/[an unknown] location" Appendix B *** Page 47. Should be "UTC" rather than "GMT". Should the OSName_t have entries like "windowsxp", should this be just "xp" as the Windows part is already spoken for in the OSFamily_t Could the xrootd protocol be added to StorageAccessProtol_t. AccessLatency_t The descriptions seem wrong to me as they use technologies rather than describing the latency. Here's my attempt: online: files with online latency are available for user activity with a low latency. The precise definition of "low" may be system-specific, but will typically be much less ten seconds. nearline: files with nearline latency will have typically latencies greater than those of online files and are typically satisfied without human intervention. Average latency for a requested files will be implementation-specific and may depend on the available hardware, but a typical value is in excess of a minute. Storage systems may undertake optimisations so that, under special circumstances, nearline latency may approach that of online latency. offline: storage that requires manual, human intervention to retrieve the data. Typical latency will depend on SLA, but typical values may exceed a day. ... and on to Storage Entities tomorrow! Cheers, Paul.