Re: Updated RDFa API spec

On Apr 2, 2011, at 19:37 , Manu Sporny wrote:

> Hey Ivan,
> 
> Apologies for the delayed reply... I have too much on my plate at the
> moment, so it's taking me a little longer to respond.

No worries!

<snip/>

> 
>> 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.
> 
> I see your point. I also see the point where (as an RDF head), I'd much
> rather work in Projections than I would in triples. That is, I'd like to
> be able to access things at the triple level, but would prefer to map
> triples to objects and work in those.
> 
> To put this in perspective, we do this quite often when working with
> databases... we map from the relational model into a more
> object-oriented model to work with our data. The relational model is
> good for storage and querying, the object model is good for manipulating
> and working with data.

I see that point indeed

> 
>> 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...
> 
> Well, we could make the dependency fairly lightweight, in that the
> /only/ items that would be required would be "Projection" and possibly
> "Profile" and "DocumentData"?
> 
> Speaking from a purely design standpoint, RDFa is designed on top of
> RDF... the APIs may want to mirror that in order to not confuse people.
> We want the RDFa API to be independent of the RDF API... but we also
> want some degree of design cohesiveness.
> 
> To look at it from another direction, if we put "Projection", "Profile"
> and "DocumentData" in the RDFa API - then does that mean that the RDF
> API depends on the RDFa API? That direction isn't a very clean design
> either.
> 

But... is it so that the implementer of the RDFa API is supposed to rely on an RDF API implementation? We may want to be able to say that implementation X can be done directly with an RDFa parser, *without* having to rely on or, worse, without the necessity to implement the RDF API (which will have another user community). What I fear is that by putting in such dependencies we will end up with this.

Though certainly not nice, I wonder whether replicating the interface may not be a viable option. In fact, I can imagine (without having changed it) that the Projection on the RDF API level may have some additional features due to its position within the RDF API...

<snip/>

> 
>> 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.
> 
> That's true...
> 
>> 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
> 
> I don't know if placing setMapping() on Projection is the correct
> direction. What is the behavior when you call setMapping() twice on an
> object? Are the properties set via the previous setMapping() call on a
> JavaScript object destroyed? For example if I do this:
> 
> MAPPING A ==> {"http://xmlns.com/0.1/foaf/name", "name"}
> MAPPING B ==> {"http://example.com/foo", "foo"}
> 
> proj.setMapping(A);
> proj.name
> 
> and then I do:
> 
> proj.setMapping(B);
> proj.name
> 
> Should 'name' still be accessible?

Yes. Consecutive calls to mapping just adds new mappings (and yes, may override older ones). It is like a dictionary. 

> If not, what's the algorithm to
> delete? What happens if someone creates a property called 'name' and
> then a new mapping is set that overwrites 'name'? I'm not saying that
> these questions don't have answers - it's just that the approach creates
> lots of corner cases. I'd much rather have the interface for Projections
> be simple and have the mapping as a part of the query mechanism. That
> is, once you get a Projection back - it is fairly static unless the
> developer changes it.
> 

I can see the point. But then the other approach is to put optionals on getItem*** calls. So let us see that below...

(As an aside: this may be a possibility that an RDF API may offer to its (clearly more advanced) users but not to RDFa...)

>> and that is it. Otherwise we seem to create confusion with too many
>> optional parameters here and there...
> 
> This is my opinion, but I think that many JavaScript developers are just
> fine with lots of optional/type-specific parameters. Just look at jQuery:
> 
> http://api.jquery.com/add/
> 
> ... optional parameter city. Further evidence in the ajax() call for jquery:
> 
> http://api.jquery.com/jQuery.ajax/
> 
> Even the optional parameter 'settings' has optional parameters. I think
> as long as all of the query parameters have a 'mapping' object as the
> last/n-th parameter, we're good. That is, as long as we're consistent, I
> don't think it'll be confusing.

Ok. As you know I am not a Javascript programmer so it is not my place to criticize that. If the JS community is happy with an optional parameter forest (or city:-), then I have no objections... But then the spec has to be changed to add those!

> 
>> 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...
> 
> Yes, we could provide a 'settings' parameter as the last parameter:
> 
> var settings = {"mapping": {}, "value": "adfasf"}
> document.getItemsByProperty(property, settings)
> 
> Lots of jQuery libraries do that. However, I don't think our API is
> complicated enough to require that. Let me see if I can add the mapping
> parameter w/o causing too much confusion. If, after looking at it, it's
> clear that things are confusing - we can try the 'settings' parameter
> approach.

Yeah, this setting is ugly. Let us try to avoid that:-)

> 
>> 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. 
> 
> Hmm, I think I meant that the query is the same (and I wasn't thinking
> about the mapping when I wrote the text)... but you're right. The two
> calls are different in the objects that they return.
> 
>> 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.
> 
> Right. I think we should add the mapping to the get* call. What do you
> think?

See above.

> 
>> 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?
> 
> The last time we talked about it, I remember consensus being "the
> element that contains the actual @rel/@rev/@about/@property/etc.
> Otherwise, things get very confusing/metaphysical - we get into
> discussions about which element "truly defined a property".

I agree. But the specification should clearly reflect this.

> 
>> <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?
> 
> Good question. I don't have a good answer. My gut tells me that it
> should return the <span>, regardless of whether or not @typeof was used.

I agree. I happen to use @rel="rdf:type" fairly often because @typeof has side effects with the creation of blank nodes in some cases (b.t.w., as a side issue, I must admit I find the side effect feature of @typeof confusing. I am not sure it was wise to define RDFa 1.0 that way after all, but that is now history...)

> 
>> <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>...
> 
> It would return the <p>

Ok. I agree. Again, it should be clearly defined

> 
>> We will have to go through all these niceties, and I predict that
>> will lead to a lot of corner cases...
> 
> Unfortunately, yes. As I've said before, the getElements* calls are
> going to be a huge pain in the ass.

You said it:-)

> 
>> 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. 
> 
> Yes, you are correct.
> 
>> But, more importantly, what does 'first' mean? In which order?
> 
> It means the first value in document-declaration order per the triple
> emission rules in the RDFa processing rules.
> 

Ok. It is very important to document that, because RDF does not have this notion, which may be confusing. Ah! And, by the way, the notion of order does not make any sense if Projection is on the RDF API level, so we may have two different, though similar interfaces here!


>> 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...)
> 
> I don't see any way around the ordering issue, unless we were to always
> return an array from the .get() call. If we do that, working with the
> API becomes far more painful. That is, this becomes standard practice:
> 
> var name = proj.get("foaf:name")[0];
> 

As I said, what this tells me is that the Projection for the RDFa API and the RDF API are _not_ the same. That may be the way to handle this...


>> 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...).
> 
> I agree. Mark wanted lots of examples up front - perhaps we don't need
> those as much now?

Exactly. It is nice to have examples, but that is an overkill.

If we all agree, I am happy take them over and fold it into the primer as additional examples at the end of the current text, because they are interesting for the reader.

<snip/>

> 
>> 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.
> 
> I'm torn on this. I see your point, I also think it helps people
> understand where this API fits into the larger picture. If someone gets
> confused by the diagram, I think we should move it. Until someone gets
> confused, I think we should keep it where it is. What do you think?

I believe moving it to an appendix is better. The main flow of the text is for people who care about RDFa only.

<snip/>

Thanks!!!

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