[glue-wg] GLUE 2.0 Specification - draft 41 - Working Group Last Call

[Paul Millar]

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/1297176/1296842/4282436/ISO_2955-1983E_repr_of_SI_units_with_limited_char_sets.pdf?nodeid=4289384

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.