Re: Review of Service Description Draft

Nico,

Thanks for the review. I've made some changes based on your feedback, and will make more as described below. However, I'm unsure of some of the issues you raise. I've commented on some of them inline.

On Jan 13, 2011, at 4:18 AM, Nico Michaelis wrote:

> I noticed some issues, although I have not yet found anything serious.
> 
> Major issues:
> * There is no comment on vendor specific extensions to the description.
> Maybe they should be encouraged, noting that orthogonal namespaces must
> be used?

Do you think this is necessary, or is extension an implicit feature of the service description being encoded in RDF? I'm not sure how "vendor-specific" extensions would be any different than any other extensions, but the example service description already shows the use of extending the description with terms from voiD and SCOVO (as you noticed). If you believe such a comment is necessary I can work on some text. (Also, as described below, I'll add text to the example SD about the specific use of scovo/voiD.)

> * There is no way to characterise parameters taken by a function
> described by sd:extensionFunction .

There are other vocabularies that might be used for this (e.g. SPIN), but I think it's outside the scope of the current service description vocabulary.

> * Section 4 (Example): An URL in the sd namespace appears that is not
> defined in the document (sd:ScalarFunction). In older drafts
> sd:ScalarFunctions appears but it has been dropped.

Fixed. :ScalarFunction is now just :Function.

> Also the namespace scovo appears without noting that it is used for
> statistical information or where to find more information about it (the
> where question also applies to the voiD). We should link them.

I will add text describing the use of scovo/voiD in the example service description. Also, I've made some changes to the example SD's use of scovo/voiD based on the recent publication of an updated voiD vocabulary.

> Moreover
> I think that the example prefix should point to
> http://example.org/example# and not to "http://example/"; See RFC 2606.

The ex: prefix declared in the example wasn't actually being used, so I've removed it.

> We should extend the example. How about sd:supportedLangugage
> sd:SPARQL11Query and sd:resultFormat statements?

Added to the example.

> Minor issues:
> At some points I found some minor mistakes or some complex language
> constructions which should be simplified for clarification - see
> suggestions below.
> 
> * Abstract after @discovering: missing comma?
> * Abstract @2nd sentence: Such ... which : Complex -> I would replace
> that with "Using such a description" a client or end user ...
> * Introduction @1st sentence: "is a way of describing": Complex -> "lists"

Fixed.

> * Introduction @1st sentence and many times throughout the document:
> "made available via the SPARQL Protocol" -> Isn't that superfluous? I
> think we can drop that phrase most of everywhere.

I don't think it's superfluous as SPARQL is used in ways other than through the HTTP protocol. This document specifies how to retrieve a service description from a SPARQL endpoint that is made available via the HTTP-based protocol. It doesn't specify how you'd retrieve a similar description if, for example, you were using a native API.

> * Introduction @1st sentence and many times throughout the document:
> "service description" -> appears in different flavours; in capital
> letters when preceded by "SPARQL", otherwise in lower-case. I think we
> should either stick to one formulation or use capitals throughout.

I'll go through and make the capitalization consistent.

> * Accessing a SD: the serialisations are not linked.

Do you mean the single reference to RDFa? I'll link that, but didn't know if you were referring to more than just that.

> * 3.2.2 @1st: language -> languages

Fixed.

> * 3.2.4 @1st: aggregate operation -> aggregate function - that's how
> they are called in the Query Doc.

I had originally referred to them as aggregate functions, but made the change based on concerns expressed by SteveH about these operations not being proper functions. I see that they are now referred to as "set functions" in the Query editor's draft. I will align the terminology with the query document.

> * 3.3 @1st: here -> above ?

I believe "here" is appropriate. For context, the full sentence is:

"In addition to the instances listed here, the following documents list instances that may be used with the properties listed below:"

The "here" in this sentence refers to (the subsections of) section 3.3. No instances are defined "above" section 3.3. "Below" might be more accurate, but then I think the double use of "below" might be confusing, one to the 3.3.* subsections and one to the 3.4 subsections.

> * 3.4.8 following the listing of subPropertyOf and domain is a sentence
> that repeats the listing - that doesn't occur anywhere else.

Fixed.

> * @@ some editor notes still in there.

There are two that are blocked by future publication of other documents (Query and Protocol). The others are for the keys in the Other References section. I will see that these reference keys are updated.

thanks,
.greg

Received on Friday, 14 January 2011 22:20:25 UTC