Re: RDFa API: thoughts on PropertyGroup

Hi Toby, Manu,

thanks for the responses, and sorry for my late feedback (had a really
busy week).


2010/11/7 Manu Sporny <msporny@digitalbazaar.com>:
> On 11/06/2010 07:49 PM, Niklas Lindström wrote:
>> 1. The name of the interface "PropertyGroup". Since the methods used
>> to retrieve these are named "getItemBy[...]", why is it not named
>> "RDFItem" or similar? Just a detail perhaps, but the naming of things
>> is quite important IMHO. (It could also be called Description, in
>> honor of the "D" in RDF.. ;) )
>
> Mark and I went back and forth on this a number of times. We discussed
> many names - "Item", "Object", "DataGroup", "Descriptor", "Info", etc.,
> but none of them were as work-able as PropertyGroup. We decided to move
> on and try naming PropertyGroups later as we could spend a very long
> time bike-shedding the name.
>
> So, a number of us agree with you - PropertyGroup isn't the name that we
> want to end up with in the RDFa API. I do like "Description" or
> "ResourceDescription".

Sounds good. I'm fine either way, although ResourceDescription is a
bit long-winded. I like Description (it's the name I've used in the
libs I work on). (Of course, the methods returning them are called
"getItemBy[...]", but that may still be ok.)


>> 2. The PropertyGroup should have an attribute for the subject it
>> represents the properties of ("readonly attribute RDFResource
>> subject;").
>
> Hmm, I thought that was in there - in any case, it should be. I think
> that perhaps the last time the interface was edited, the subject was
> supposed to be placed in the 'info' property, so this could give you the
> subject:
>
> var subject = pg.info["subject"];
>
> Although the documentation doesn't say that, does it. What do you think
> of the above mechanism?

I'd much prefer a dedicated "subject" (or "about") attribute, since
it's central to
how PropertyGroup works (and is encapsulated by it upon construction).


>> 3 a. It would be really convenient to easily get a PropertyGroup for
>> an RDFResource (i.e. IRI:s and BNodes), so I suggest adding a method
>> to RDFResource for getting a PropertyGroup with the given resource as
>> subject, such as "getItem()". This is to avoid having to repeatedly
>> call "document.getItemBySubject(...)" when traversing linked
>> resources.
>
> Perhaps. We're trying to keep the interface as light-weight as possible.
> This is the code we'd have without your change:
>
> var pg = document.getItemBySubject(resource.toString());
>
> and this is the code we'd have with your change:
>
> var pg = resource.getItem();
>
> I don't think adding the interface simplifies the code enough to warrant
> the addition. Am I missing something? What do you think of the more
> complicated code example?

Viewed like this, it makes less sense to add my change, since resource
is on a lower level in the API (as both you and Toby also remarked).
But since we have the PropertyGroup utility mechanism to reduce
cumbersome code, I think it should be improved to avoid having to do
the complicated procedure of calling "document.getItemBySubject" when
one needs to collect or traverse descriptions (see below). I therefore
think the "3 b" suggestion, discussed below, is more appropriate.


>> 3 b. If this breaks the layered abstraction (RDFResource being "lower"
>> than PropertyGroup), it might be better to have something like
>> "getItems(...)" on PropertyGroup (either failing or filtering if the
>> retrieved values aren't all RDFResource:s).
>
> It does break the layered abstraction a bit. So is this what you mean by
> the statement above:
>
> var pgs = pg.getItems(???);
>
> What would you pass getItems()? An RDFResource? If so, wouldn't you only
> get one PropertyGroup back? A code example would help to understand
> where you're coming from.

I'd pass a CURIE DOMString, like:

    var friendsPGs = personPG.getItems("foaf:knows");

For each referenced *RDFResource* a PropertyGroup (Description..)
would be created. If some objects of the matching triples instead are
Literals, they could either be skipped or an exception could be
thrown. I'd suggest the former, since the intent of getItems is to get
described resources (not to scan for unexpected literals).

As I see it, the PropertyGroup is a utility for traversing graphs and
getting values for resources. It knows about the graph, and has a
bound subject. It therefore seems viable that it should be able to
create new PropertyGroups for resources referenced by the current
subject. This makes for simpler code, where one can e.g. do stuff
like:

    var me = document.getItemBySubject("http://example.org/me");
    var homepage = me.getItems("foaf:homepage")[0];
    var url = homepage.subject;
    var title = homepage.get("dc:title")[0].value;

Or in one chained expression:

    document.getItemBySubject("http://example.org/me#self").getItems("foaf:homepage")[0].get("dc:title")[0]

As a complement to a getItems, there could also be a "getItemsByRev",
which would work like:

    var creations = me.getItemsByRev("dct:creator");

(Of course, with unknown data there may be "NullPointerExceptions"
anywhere in the above code. Some languages handle this better than
other; some API:s provide helper methods for these cases (such as
"getOne/getAll", etc). But that could be left to something even more
high level, such as a jQuery-like utility upon the RDFa API (mmm,
sparql 1.1 paths ;D). Note also that title should really be retrieved
by scanning all literals for one with the appropriate language (and a
high level utility should provide helpers for that as well).)

You can also compare this code to the node-oriented Jena API [1],
where the Resource type corresponds somewhat to the PropertyGroup
interface. (I definitely recommend to compare the RDFa API to the Jena
API in general to see if there may be more things to align. The Jena
API is proven and seems sustainably popular.)

What do you think?

Best regards,
Niklas

[1]: http://jena.sourceforge.net/tutorial/RDF_API/index.html#ch-Navigating%20a%20Model

Received on Saturday, 13 November 2010 12:42:33 UTC