ISSUE-28: Re: New Issue(s)

On 06/24/2010 11:59 AM, Nathan wrote:
> 1: This documentation looks a bit wrong..
>   DataStore.createPlainLiteral( value, language );
>   value  DOMString  The value of the IRI. The value can be either a full
> IRI or a CURIE.
> ?? the value of a PlainLiteral must be an IRI or CURIE ??

Fixed. Now reads:

The value of the Plain Literal, which is usually a human-readable string.

> 2: CURIE resolution..
> 
> var contextA = document.data.createContext();
> var contextB = document.data.createContext();
> contextA.setMapping( 'a' , 'http://example.com/a#' );
> contextB.setMapping( 'a' , 'http://example.com/b#' );
> var store = document.data.createStore();
> var triple = store.createTypedLiteral( 'something' , 'a:test' );
> 
> will that a:test resolve to:
>   http://example.com/a#test -or- http://example.com/b#test ?

Good catch, Nathan. This isn't explained very well in the document and
there were a couple of IDL bugs that confused the situation.

I removed the readonly qualifiers for all of the DocumentData
properties. This ensures that you can swap out context, parsers, stores
and query mechanisms at runtime. To answer your question, the default
DataContext stored in the DocumentData object determines how CURIEs are
resolved. There is now an explicit paragraph in the DataContext section
that explains this mechanism:

"""
In general, when a CURIE is resolved by the RDFa API, the current
DataContext stored in the DocumentData object must be used to perform
the resolution. This is to ensure that there is only one active
DataContext in use by the RDFa API at any given time. The DataContext
stored in the DocumentData object may be changed at runtime.
"""

We had assumed that anything that needed to resolve CURIEs, such as the
DataStore, would have access to the default context and would use it to
resolve CURIEs. I'm not certain of the best mechanism to ensure that the
DocumentData context object should be used for all CURIE resolution.
However, I also don't think that we should mandate how an implementer of
the RDFa API should ensure that the current DataContext stored in the
DocumentData object should be accessed. Some might choose to use a
reference that is updated, others a pointer, and others a library-global
variable to track the latest DataContext.

> the same issue arises for registerTypeConversion, if I created two
> different functions to handle a type of xsd:whatever then which would be
> used?

The answer above applies to this as well. The current DataContext stored
in the DocumentData object will be used to perform the type conversion.

> In other words, DataContext is completely decoupled from everything
> else, yet most other interfaces depend on DataContext to provide CURIE
> resolution and typed literal conversion (there are quite a few examples
> throughout the doc)

Hopefully now the DataContext doesn't seem to be completely decoupled
and it's clear that anything that does CURIE resolution or type
conversion should use the current DataContext from the DocumentData object.

I also exposed another method to DataContext called resolveCurie(). It
was implied thatanyone implementing the RDFa API must provide this
method internally, but may also be useful to developers using the RDFa
API. For example, it may be useful to expand CURIEs to full IRIs for
display on a web page for debugging purposes, or to create click-able
links for <a href=""> code snippets.

> 3: TypedLiteralConverter
> Just how would one create a new TypedLiteralConverter? There's no
> constructor, and further DataContext.registerTypeConversion needs an
> instance of TypedLiteralConverter but specifies that the converter param
> should be 'A function that converts..' (indicating
> TypedLiteralConverter.convertType or a callback rather than an instanceof)

Note that the TypedLiteralConverter interface has a [Callback]
attribute. This means that it can be implemented as a simple ECMAScript
function. More on [Callback] here:

http://www.w3.org/TR/WebIDL/#Callback

> 4: DocumentData.createStore( type ) - what's the type for? why is it not
> nullable and not optional when no examples actually pass in a param?

The not being optional part was a bug, thanks... fixed. I also added
more documentation to make it clear why the type parameter is there:

"""
Creates a DataStore and returns it. If the type is not specified, a
DataStore must be created and returned. Alternatively, developers may
provide other DataStore implementations such as persisted triple stores,
quad stores, distributed graph stores and other more advanced storage
mechanisms. The type determines the underlying DataStore that will be
created.
"""

> 5: Document.getElementsByType(type) and getItemsByType(type) where type
> is a DOMString, should this not be IRI or CURIE?

Nope. Already covered this in the previous e-mail sent to you, but we're
trying to have very clean, simple, string-based developer interfaces to
the API.

> 6: How does one create a new DocumentData instance? there's no way to
> set the .store/context/parser/query properties (they're all readonly)

All of these properties on DocumentData are now read/write. A method has
been added to create a new DocumentData instance on the Document object.
This has been done in preparation for addressing ISSUE-33, which will
require us to create new convenience methods for creating all of the
RDFa API interface objects.

-- manu

-- 
Manu Sporny (skype: msporny, twitter: manusporny)
President/CEO - Digital Bazaar, Inc.
blog: WebApp Security - A jQuery Javascript-native SSL/TLS library
http://blog.digitalbazaar.com/2010/07/20/javascript-tls-1/
http://blog.digitalbazaar.com/2010/07/20/javascript-tls-2/

Received on Sunday, 1 August 2010 23:22:18 UTC