Re: Updated RDFa API spec

Hey Manu,

this is a major step forward. And I also think it has really paid off to separate the RDF API, it made this document simple and that is important for the community that we address.

Some generic comments on the issues you raise, followed by my own comments.

-----

Moving the DocumentData and Projection interfaces to the RDF API: I am not convinced. The RDF API level is for RDF heads. They have no problems thinking in triples. I guess we will have some sort of an API to get to triples with simple patterns, something like the Python idiom of:

for (s,p,o) in graph.triples((subj,None,None)) :
  ...

which covers most of the usages of the Projection. This Projection stuff is important for RDFa Web Application developers, but that is a different crowd. 

As you say, moving those interfaces would mean that there would be an obligatory dependency of the RDFa API on the RDF API which will become a bit of a complication both for authors and implementers...

----

The current interface relies on calls like getItemBy***(res) or getElementsBy***(res). However, I have no means of finding out what subjects, properties, or types are available in the document in the first place! Don't we need, on the Document interface, methods like

document.getAvailableTypes()
document.getAvailableSubjects()
document.getAvailableProperties()

each simply returning an array of URIs?

----

There is a certain confusion, at least for me, on the setting of 'mappings' for a Projection, ie, the mapping of a possible attribute name to a URI. You give an example in the text:

var albert = document.getItemBySubject("#albert", {"name": "foaf:name"});
var name = albert.name;

but the mapping is _not_ defined for the getItemBySubject() method, so I suspect the example is simply wrong. I have also seen that you can set the mapping query method with an optional parameter (which is fine), but that is the only place where this is defined.

I would propose to

- keep the query method's optional parameter, this is for advanced users anyway
- add a setMapping() method to the Projection interface, so that advanced users may set their mapping on the output of the getItemBy*** methods

and that is it. Otherwise we seem to create confusion with too many optional parameters here and there...

If all this was in Python, then we could use keyword arguments. Ie, one could define

document.getItemsByProperty(property, value=optionalValue, mapping={...})

the beauty of that is that, in python, all the variations are automatically valid:

document.getItemsByProperty(property)
document.getItemsByProperty(property, mapping={...})
document.getItemsByProperty(property, mapping={...}, value="adfasf")
document.getItemsByProperty(property, value="adfasf", mapping={...})
document.getItemsByProperty(property, value="adfasf")

Is it something that can be done in WebIDL/Javascript? If so, we can of course do it this way, but I have the impression that, otherwise, it becomes convoluted...

----

A bit related to my comment above, though probably just an editorial issue: section 3.2, advanced concepts, the text says:

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

is the same as 

var people = document.data.rdfa.query({"rdf:type": "foaf:Person"}, 
   {"name": "foaf:name", "age": "foaf:age"});

And this is incorrect, because you cannot set the mapping as part of the getItemsByType call. It should say:

var people = document.data.rdfa.query({"rdf:type": "foaf:Person"});

Or, we can say

pr = document.getItemsByType("http://xmlns.com/foaf/0.1/Person");
pr[0].setMapping({"name": "foaf:name", "age": "foaf:age"})

If we add the extra setMapping method to Profile.

------

I have some troubles with the specification of the getElementsBy*** methods.

The specification of getElementsBySubject says "explicitly specified the given subject". First of all, the same formulation should be used for getElementsByProperty otherwise it is not clear what happens to hanging rels: which element should be returned? The one that specifies, or the one that really makes use of it down the line? 

But there are other issues that need to be specified.

Eg, if I have

<span about="#me" rel="rdf:type" resource="foaf:name">...</span>

should

getElementByType("foaf:name") return the <span>, or is it reserved for an explicit @typeof usage?

Or, in: 

<p about="res1" rel="something" resource="res2">
   <span rel="somethingelse" resource="res3"/>
</p>

will document.getElementsBySubjects(res2) return <p>? After all, that is the element that sets the subject for <span>...

We will have to go through all these niceties, and I predict that will lead to a lot of corner cases...

----

The specification of 'get' in Projection says that it returns the 'first property with the given name as a language-native datatype'. First of all, I guess it returns a value for that property, not the property itself. But, more importantly, what does 'first' mean? In which order? If the API is implemented on top of an RDF API, then that order may be lost, after all, RDF does not keep the order... Or do we require an XML document order (in which case the implementation of the API might become a bit more complicated insofar as it is not a layer on top of the RDF API in this sense...)

----

Everything that follows are really editorial issues.

I think there are way too many examples in the introduction. I wonder whether we need any of those examples at all (note that none of the coding examples use those!). I would propose to move out all those examples into the RDFa Primer document as additional examples, rather than having them in this document. They show RDFa, not the API (of course, I understand that what can be done with those RDFa extracts rely on the API, but that can still move into the primer...).

B.t.w., regardless of where we put it, why using safe CURIE-s in example 1.6? They are really mostly unnecessary in 1.1, let alone the fact that I am not sure safe CURIE-s are kosher in properties in the first place, even in 1.0... I propose to remove those.

The text underneath the concept diagram, as well as the diagram itself, though correct, may be more confusing than helpful. This document is mostly for those who do _not_ care about the RDF API level. The text and diagram is only helpful for those few who do. I would propose to move the whole diagram and underlying text away into an informative appendix.

In section 3.1, basic API, document.getItemBySubject(type) -> document.getItemBySubject(subject), etc. I guess it was copy-paste, but argument name should be different

I personally still have difficulties to read WebIDL (ok, shame on me...); I wonder whether it would not be worthwhile to have an informative appendix on how this interface looks like in ECMAScript. The interface has become pretty small, which is great, so that would not add too much to the document, and would be really helpful nevertheless...

That is it...

Thanks!

Ivan


On Mar 19, 2011, at 21:49 , Manu Sporny wrote:

> Hi folks,
> 
> I wasn't able to get in touch with Nathan today, but still went through
> the entire RDFa API spec and updated it based on what I believe to be
> the current direction.
> 
> http://www.w3.org/2010/02/rdfa/sources/rdfa-api/
> 
> The language was double-checked and tightened up in areas that needed
> it, technical corrections were also made throughout the document.
> Overall, the size of the RDFa API spec is shrinking but the overall
> functionality remains high (which is really great - exactly what we
> wanted to happen). Around 80% of the document is non-normative
> explanation, with the interface definition (roughly 5 printed pages)
> being the only normative requirement.
> 
> I also updated the concept diagram to reflect what is probably going to
> happen with the RDF API:
> 
> http://www.w3.org/2010/02/rdfa/sources/rdfa-api/#concept-diagram
> 
> Merging the Projection interface with the Property Group interface went
> really well - we only have Projections now and many of the interfaces
> now either return Projections or DOM Elements:
> 
> http://www.w3.org/2010/02/rdfa/sources/rdfa-api/#projections
> 
> We still may decide to move the Projection and DocumentData interfaces
> into the RDF API and make those the only requirements that the RDFa API
> has on the RDF API. I tried to design the linkages such that we could
> take the RDFa API to REC independently of the RDF API. We may or may not
> end up doing it this way in the coming months. I'll need to discuss more
> with Nathan, Benjamin, Mark and Ivan before making those changes.
> 
> The RDFa API document could be published as a Working Draft at this
> point, but we'll probably wait a bit to make sure that Nathan and I are
> synched up on the RDF API before trying to push two new WDs out.
> 
> -- manu
> 
> -- 
> Manu Sporny (skype: msporny, twitter: manusporny)
> President/CEO - Digital Bazaar, Inc.
> blog: Payment Standards and Competition
> http://digitalbazaar.com/2011/02/28/payment-standards/
> 


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