Re: New Editors draft of RDFa API spec

On Sep 5, 2010, at 02:33 , Manu Sporny wrote:

> I spent most of the day today going through the RDFa API examples and
> making editorial changes - fixing examples and bugs mostly. There is a
> new version of the RDFa API spec available here:
> 
> http://www.w3.org/2010/02/rdfa/sources/rdfa-api/
> 

Manu,

here are my comments. They are not in any particular order or, more exactly, they are mostly in the order the document; I just made notes as I went along. All in all: kudos:-)

Ivan

----
I miss much more cross links. If I see a term 'property group' somewhere, it should link to its definition. Shane did a marvellous job in the RDFa Core document in this respect, we should have that, too...

----
The document uses the latest editor's draft version of WebIDL:

http://dev.w3.org/2006/webapi/WebIDL/

instead of the latest, official version

http://www.w3.org/TR/2008/WD-WebIDL-20081219/

This is significant because, for example, 'stringifier' does _not_ appear in the 2008 version, it took me some time to find it... I think the reference should refer to the editor's draft for now.

----
The 1.2 example is a bit stange. It is correct, no doubt about it, but it is a way of using RDFa that might raise a lot of eyebrows. Indeed, it is really using <div>-s in nested manner to encode RDF without any textual content except for one paragraph. 

Again, the example is correct. But a question that might come to a casual reader: why is the usage of RDFa justified for this example? One could encode the RDF code in, say, turtle or RDF/XML and let it retrieved run-time...

Bottom line: maybe, for didactic reasons, using a different example might be better.

----
1.3: The indentation of the example with the dangling '<a' is a bit strange...

----
1.4: indentation is missing

----
1.5: why the nested span in the middle?

----
2. I wonder whether the right term to use in the document is JavaScript or ECMAScript. Looking at http://www.w3.org/TR/2010/CR-geolocation-API-20100907/ they use ECMAScript... Probably a global change should be done...

B.t.w., There is a missing conformance requirement section. The geolocation document seems to contain a good one, also referring to the binding issues on webidl (ie, that the ecmascript binding to webidl must be used).

That also affects a bit the last paragraph in section 2. The WebIDL document includes a binding to Java, so it might be good to refer to the fact that Java implementations should use that one. Nothing can be said about the other languages, though...

----
2.1. Goals: although there should be a general discussion on this, it may be worth emphasizing that not only the API allows for non-RDFa parsers to be used, but the interface offers some sort of a generic API to RDF...

Editorially: I thing forward links into the document would be useful for terms like property groups...

----
2.2 Concept diagram: I am not sure how, but it might be good to have on the diagram and the accompanying text, references to some of the 'sections' of the document. We use, for example, the term 'RDF Interfaces' in the text; maybe using the same term on the diagram would be good (if the diagram is in SVG, it should be a clickable link to the relevant section...). Same for the others and the text itself.

----
Examples for manageing elements with data: the terms 'nodes' and 'elements' are used interchangeably, and that is a bit disturbing. I know, they are 'Element Nodes' in DOM parlance but, nevertheless... let us try to keep to one (I do not really care which one, to be honest). Note that the specification uses 'node' (of course), so maybe we should keep to that.

----
Is the 'Issue' entry on 'Modifying DOM Element' still relevant?

----
3.2.1, first example uses the query, but it is not clear why one would use that one instead of

var people = document.getItemsByType("http://xmlns.com/foaf/0.1/Person");

which achieves the same thing.  I think another example should be found that cannot be expressed with the basic calls... Or making it clear that *that* particular call can be done in this case, but look at the examples below that become more complicated...

I must admit I had to look up what this foaf:myersBriggs property means. Can't we use a somewhat less esoteric example?

----
PlainLiteral definition. Why does one need a stringifier for a value and not for the language attribute? Aren't both strings in the first place?

Example later: it says that literal.toString() can be used. Where is that defined? Put it another way, shouldn't it be defined on the RDF Node level so that it would be inherited by everyone? (Or is it defined in WebIDL in general and I just do not know it? Maybe worth emphasizing for outsiders like me...)

The comments says, for example, "The API supports direct assignment of PlaingLiteral values" but the example is not assignment but just accessing the attribute. Besides, those attributes are defined to be 'readonly'. Isn't something wrong?

----
TypedLiteralConverter interface: I do not understand what the targetType parameter is for. Either give a good (and convincing:-) example, or drop it if it has only a very restricted use...

----
DataStore interface: the latest version of Web IDL seems to have _dropped_ the [IndexGetter]. Quoting from appendix C:

[[[
Turned [Callable], [IndexGetter], [IndexSetter], [IndexCreator], [IndexDeleter], [NameGetter], [NameSetter], [NameCreator], [NameDeleter] and [Stringifies] into real Web IDL syntax using caller, getter, setter, creator, deleter and stringifier. Dropped [NoIndexingOperations] in favor of an omittable keyword that can be used on the above six special operations.
]]]

this part should be redone then... which may mean that the method 'get' would be gone, too?

----
Still the DataStore interface:

Just to specify it clearly: if I 'add' a triple twice, then the triple will not be repeated, right? It sounds obvious but some triple stores (like AllegroGraph) does not do that check...

I continue to be puzzled by the filter method, ie, by the fact that it returns another DataStore, rather than just an array of RDFTriple-s. I just do not get it... The PropertyGroup, for example, returns a 'Sequence' argument, ie, it is possible to just return an array. This should be discussed.

I am not fully convinced about the necessity of having the 'forEach' method. Sure, I can see its utility, but its functionality can easily be programmed by a cycle through the triples of the store and it seems to add too much to the Data store interface. I would consider removing it altogether, including the DataStoreIterator interface.

----
Data Parser interface.

The current parser is defined for a DOM-like parser, eRDF, Microdata, whatever. But I would like to be able to have a turtle parser that takes a URI as an argument, rather than an Element. Would that be possible to do in WebIDL? In any case, it would really be good to have that extension point to any type of parsing...

I am not sure what the role of the store is for a DataIterator. They way I understand it:

- parse puts all the triples into the Store and then one used the DataStore interface
- iterator just gives you the triples one after the other. The user 'may' decide to add it to a store, of course, but that is outside the realm of the iterator, isn't it?

If so, I actually wonder whether the DataParser and the DataIterators are not two completely different interfaces, for different usages and it may be better to separate them altogether.

----
Property group interface.

Editorial issue: the property group template section comes a bit out of the blue, because the query is defined later. I would expect this section to be moved down to the definition of Data Query...

----
Property group template section

I would think we should reuse the example on google snippet we have at the beginning of the document. Let us proliferate those examples too much...

----
That may be a stylistic issue: isn't it more logical to have the getItemsBy*** methods defined on the DocumentData interface rather than the RDFaDocument? After all, those can be considered as shorthands for specific query methods. I may also move the getElementsBy* methods there for symmetry, though they are closer to the 'usual' DOM methods.




----
Ivan Herman, W3C Semantic Web Activity Lead
Home: http://www.w3.org/People/Ivan/
mobile: +31-641044153
PGP Key: http://www.ivan-herman.net/pgpkey.html
FOAF: http://www.ivan-herman.net/foaf.rdf