Re: Comments on the API document (version of Monday

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.

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

I'm hoping it is more of a matter of presentation. More below...

> - there are a number of places with, at first glance, overlapping
>   functionalities. Eg

So, I was trying to err on including too many ideas at first, and then
cutting the duplication or overlapping functionality out at a later
date. Some of these things, like filter() vs. iterate() vs. select() are
best discussed when we have full thought out specs in front of us
instead of assuming we know what the other is talking about when they
say "a filter-based mechanism" or "an iteration-based mechanism".

There is some overlapping functionality... we'll have to decide what to
keep and what to remove as a group.

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

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


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

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

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

> 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");

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

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

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

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

Received on Thursday, 20 May 2010 04:29:46 UTC