Re: Comments on the API document (version of Monday

On May 20, 2010, at 06:29 , Manu Sporny wrote:

> On 05/19/2010 02:50 AM, Ivan Herman wrote:
>> With this: I have read through the API document and I am now
>> officially and completely lost :-(
> 
> Mission accomplished!
> 
> Wait... no... that's not good.

:-)

[snip]
> 
>>   - 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
> 
> Those two things are a part of the same beast. The filter() operation on
> the store is what the developer calls to execute the filtering
> operation. RDFTripleFilter is the WebIDL definition for the function
> that filter() takes as an argument. So, there is only one filter()
> function - but we must specify both the function itself, and the
> argument that the function takes since it is a callback.
> 

O.k. I see that now, and this is due to my lacking WebIDL knowledge

(I am obviously old-skool. It somehow looks funny to me that one defines an 'interface',which for me is some sort of an abstract representation of a class, a bit like in Java, for what is a special function type.)


>>   - there is again a filter defined in the rdfa interface
> 
> There is no longer an rdfa interface, you were reading dead code - sorry
> about that. Any remnants of the rdfa interface exist in section 4.3.4,
> which is marked for deletion because it duplicates functionality
> elsewhere in the document.
> 

ok.

> 
>>   - there ia a DataIterator which again seems to be very close to
>>     the filtering
> 
> It is very close to filtering, except that the DataIterator mechanism is
> meant for low-power or low-memory devices. It was Benjamin's (very good)
> idea. When I was updating that section, I was thinking that the
> interface would not require more than 100KB of code + data to execute
> (that includes RDFa Processor + HTML document + RDFa DOM API).

That will require more explanation for me.

> 
>> 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
> 
> Agreed. In an attempt to help explain the API more clearly, I've added
> two sections:
> 
> Design Goals
> 
> http://www.w3.org/2010/02/rdfa/sources/rdfa-dom-api/Overview.html#the-design-goals
> 
> and a diagram showing the relation of all of the concepts discussed in
> the API document:
> 
> http://www.w3.org/2010/02/rdfa/sources/rdfa-dom-api/Overview.html#concept-diagram
> 
>> - 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)
> 
> Agreed. The entire section titled "Low-level Interfaces" are meant to be
> for advanced readers/implementers. Still lots of work that needs to be
> done, though.
> 
>> - 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.
> 
> We should discuss that MAY. I was primarily concerned with requiring
> that the environment be initialized in any particular order. As long as
> the objects exist when the Web developer requests access to the API,
> we're okay. I'm worried about over-specifying the exact steps.
> 

I think that there should, somehow, two ways of 'creating' or accessing the whole RDFa environment. One way should be one step and should return a reasonable default setup. The other way is the detailed setup where the user can specialize along the way. The latter is obviously for advanced users only; the former is obviously a wrapper around the latter with default settings.


> That said, the MAY could lead to issues, which means that we should
> reword that section. The prose in that entire section is far too loose
> at the moment. It needs to be reworked a few more times.
> 
>> - 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.
> 
> The main reason that there are a "large" number of interfaces (there are
> 10 interfaces) is because we're trying to create something that's
> modular and pluggable. If we integrate too heavily, it means that parts
> of the API cannot be replaced by the developer.
> 
> See "modularity and pluggability" in this section:
> 
> http://www.w3.org/2010/02/rdfa/sources/rdfa-dom-api/Overview.html#the-design-goals

Hm. To provoke: who and when decided that we need that as a design goal? I do not remember having this discussion... If the price for this level of modularity and pluggability is a very complex API that the community will reject, than we would loose on long term. In my view, simplicity may be more important.

> 
>> 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.
> 
> That's actually the approach we were trying for... certainly not there
> yet, but I think we're on the same page as to what we want.
> 
>> With that, here is my draft of this morning:
>> 
>> 1. Basic API level:
>> - RDF interfaces (IRI, Literal, etc).
> 
> Those are "complex" concepts, not basic API stuff... I can explain more
> on the call, but the idea was that all basic developers would have to do is:
> 
> var person = document.getItemsByType("foaf:Person")[0];
> 
> and then:
> 
> var name = person.get("foaf:name");

well... I have difficulties to believe that we can get away without the IRI, Literal, etc. If I have

<span typeof="foaf:Person>
  <span property="ex:dataproperty">http://www.example.com</span>
  <span rel="ex:dataproperty" resource="http://www.example.com"/>
<span>

then I would like n1 and n2 below:

var n1 = person.get("ex:objectproperty")
var n2 = person.get("ex:dataproperty")

to be different. My current feeling is that the IRI, Literal and blank node (possibly nothing else) are to be defined as basic datatypes that permeate the whole API. Then of course you may get something like what you have.

> 
>> 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
> 
> There will be default converters specified for all XSD types in
> Javascript. You're right, 80% of developers won't need to do this... but
> for the ones that define their own datatypes, or use non-XSD datatypes,
> it'll be important to allow this in the "advanced" API.

And I agree with that. But there is a presentation issue: I would prefer not to see that in the section for simple users.

I presume it is possible to edit something like:

section 1:

  interface IF {
     method1 .....
  }

section 2:

  interface IF {
     method2 ...
  }

ie, that the full definition of an interface is, editorially, spread over the text. Of course, you can have an appendix with the full definition. That is what I meant, not to remove that functionality.


>> - Notion of PropertyGroup (note that the current definition does not
>     include the origin, and should be)
> 
> Yes, Mark wants this too - it was an accidental omission. However, we
> still need to discuss /what/ the default origin should be. Is it the
> origin of the subject? Probably.

My understanding is that the property group is all about all the triples bound to one subject. If so, than the origin should be the DOM node for that subject...

> 
>> - The Document interface
>> 
>> That is it. I believe a vast majority of our users will be happy with
>> that
> 
> I agree in principle... devils in the details.
> 
>> 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
> 
> Sounds good...
> 
>> 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
> 
> Yep, looks good.
> 
>> 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...
> 
> Yeah, big concern is how difficult it's going to be to implement the
> spec. It's not a minor undertaking. We want this stuff in browsers...
> it's not going to get in there if they have to support everything we're
> talking about in this spec all at once.
> 
> Thanks for the quick review, Ivan. I made some changes based on your
> input... we'll discuss more on the telecon.
> 

Sure!

Ivan


> -- manu
> 
> -- 
> Manu Sporny (skype: msporny, twitter: manusporny)
> President/CEO - Digital Bazaar, Inc.
> blog: Bitmunk 3.2.2 - Good Relations and Ditching Apache+PHP
> http://blog.digitalbazaar.com/2010/05/06/bitmunk-3-2-2/2/
> 


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