Re: Updated RDFa API spec

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.

On 03/21/2011 06:54 AM, Ivan Herman wrote:
> 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.

Yes, I agree.

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

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

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

Yes, I'll put this in there and see what people think about it.

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

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

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

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

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

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

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

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

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

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

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

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

Ok, will do.

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

> 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

Thanks, will fix.

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

I agree, I think that would be helpful. If for no other reason, to give
people something they could copy-paste to get started.

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

Nathan had several good suggestions, while chatting offline, that I'll
try to integrate as well.

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

Received on Saturday, 2 April 2011 17:37:51 UTC