Comments on the API document (version of Monday

First of all, and enormous kudos to Manu, Sebastian and Mark, we finally have a document at one place that we can discuss. That may have been the most difficult step...

That being said, I have to give lots of apologies for my mail below. The fact is that I read the document on the plane coming to a meeting in Stockholm, and I wrote these notes a bit on the side of the meeting (and this mail in the morning before rushing to the meeting itself). I do not have the time to make it precise and worked out in details, so many things are vague and not properly worked out. Again, apologies for that, but I thought it would still be useful to have them sent out today, in time before the telco tomorrow (I will be there, I plan to go home tonight).

With this: I have read through the API document and I am now officially and completely lost:-( Sorry... Here are my impressions:

- It is hugely complicated. We had to face an uphill battle with RDFa1.0 which was accused to be too complicated for the average user. Well, we did a lot to address this issue with RDFa1.1 Core, but this API puts us back to the same level. Note that it may be a matter of presentation, I will give a draft structure below that might help

- there are a number of places with, at first glance, overlapping functionalities. Eg
   - there is a filter operation on the Store. It gives me a way to look for triples, with an optional restriction on the element where the filter should start
   - there is a separate filter defined through RDFTripleFilter interface
   - there is again a filter defined in the rdfa interface
   - there ia a DataIterator which again seems to be very close to the filtering
I am sure there are subtle differences, but I did not grasp them at first reading. We should really prune the document and get rid of any overlapping functionalities wherever possible

- there are a number of operations that, though useful for advanced users, will be and should be ignored by a majority of them. Typical examples are the possible choice of parsers or the methods to convert datatype literals into their javascript (or other language) equivalents. There is and there should be a default for all these, and the possibility to manipulate these things should be relegated into an advanced section (ie, hidden to most users)

- I do not like the introductory part of section 3 on how to initialize a data store. The text which says 'implementations MAY do the following' may lead to major problems of interoperability.

- That may be a matter of style: but I am lost with the vast number of interfaces; using this stuff begins to look like a huge forest. Personally, I would prefer a small number of interfaces with possibly a larger number of operations and that is it. Again, this may be a matter of programming style.

So, after being so negative (sorry about that) I tried to imagine how I would re-arrange the document. Apart from the pruning I was talking about, this does not change functionality, but rather presentation. My goal is that most of the people could read the first few section, could then go away and do stuff and be happy. That also means that the same interface (eg, store) may be defined through several sections, ie, not all things are defined at first, but that is fine. With that, here is my draft of this morning:

1. Basic API level:
 - RDF interfaces (IRI, Literal, etc). With restrictions: I do not want to know about the possibility of redefining the datatype->javascript object conversion; 80% of users won't do that, some defaults should prevail
 - Notion of PropertyGroup (note that the current definition does not include the origin, and should be)
 - The Document interface

That is it. I believe a vast majority of our users will be happy with that

2. Basic Store level:
 - a restricted view of store, without mentioning the possibility for parser setup and the like; again, most of our users would just want an RDFa or maybe a microformat parser.
 - the datastore stuff, ie, get, add and filter triples

3. Personalisation/adaptation
 - the extension possibilities, that were silent on in the previous sections: adding your own parser, changing the datatype->object conversions, etc.

4. High level queries
 - essentially, the query interface, allowing the mini-sparql queries

I could even imagine that we define 'levels' of API and not all implementations are required to implement all. I would probably think that a simple level is section #1 and #2 above and #3 and #4 may be relegated to a level 2, so to say. This is just an idea...

That is for now, and sorry to be so sketchy. I have to run now, and will mail this text while at the meeting...

Ivan


----
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