Re: Testing documentLoader and missing documentation for RemoteDocument

On Sep 3, 2013, at 7:57 AM, Markus Lanthaler <markus.lanthaler@gmx.net> wrote:

> On Tuesday, September 03, 2013 4:22 PM, Gregg Kellogg wrote:
>> Another thing is that it's not clear how the content-type is delivered
>> through the promise. If the dereferencable is done on the callback,
>> then the algorithm doesn't have access to it otherwise. I'd suggest
>> adding a contentType member to the RemoteDocument dictionary.
> 
> It's not required if you use the callback. The callback has to take care to
> not include the contextUrl if the media type equals application/ld+json.
> This is mentioned in the description of the contextUrl member:
> 
>  contextUrl of type DOMString, defaulting to null
>    If available, the value of the HTTP Link Header [RFC5988] using the
>    http://www.w3.org/ns/json-ld#context link relation in the response.
>    If the response's content type is application/ld+json, the HTTP Link
>    Header MUST be ignored. If multiple HTTP Link Headers using the
>    http://www.w3.org/ns/json-ld#context link relation are found, the
>    Promise of the LoadDocumentCallback MUST be rejected with a JsonLdError
>    whose code is set to multiple context link headers.
> 
> [http://json-ld.org/spec/latest/json-ld-api/#widl-RemoteDocument-contextUrl]
> 
> I think the name "contextUrl" is a bit unfortunate and contextLinkHeader or
> something similar would have been better. It's not that important though.
> 
> 
>>> [[[
>>> If the documentLoader option is specified, a conformant JSON-LD
> Processor
>>> MUST use it to dereference remote documents and contexts. The
> documentUrl in
>>> the returned RemoteDocument is used as base IRI and the contextUrl is
> used
>>> instead of looking at the HTTP Link Header directly. For the sake of
>>> simplicity, none of the algorithms in this document mention this
> directly.
>>> JSON-LD Implementations are not required to implement the documentLoader
>>> option.
>>> ]]]
>> 
>> Using the contextUrl instead of the link header doesn't address the
>> interaction of the contextUrl with the expandContext option. Either the
>> option overrides the link header or contextUrl, or they are both used,
>> in some order.
> 
> Why not? The expandContext option is handled in step 4, nothing needs to be
> changed there. In step 5, instead of looking at the HTTP Link header
> directly, the contextUrl is used (as the processor doesn't have access to
> the HTTP response anyway). So they are both used, the first expandContext
> then contextUrl. Do you think that needs further clarification?

You're right, this does make it clear.

> [...]
>>> This is not only for the documentLoader feature, right? It also tests
> the
>>> built-in document loader of JSON-LD implementations. I would thus
> propose to
>>> call these tests remote-doc-xxxx.
>> 
>> Good point, some of the tests probably need to be repeated with, and
>> without the useDocumentLoader option.
> 
> I don't know how we want to test the documentLoader. Some time ago we talked
> about adding that test to idltest because it is an API test and not an
> algorithmic test but we weren't sure whether to include the result of those
> tests in the implementation report. I still believe that the easiest thing
> would be to include those tests in idltest.

We agreed to add a useDocumentLoader option and have an implementation provide a document loader to use if this option is specified. This allows us to test the normative requirements defined for the documentLoader; the test ensures that an implementation properly handles the results or exception based on a documentLoader behaving as described.

Gregg

>> I actually got a start on this last night, and am working through these
>> tests, and my own implementation of it right now. Let me complete those
>> today, and then you might add anything else you think necessary. Nite
>> that some of it is controlled through the .htaccess tile.
> 
> OK
> 
> 
>> If you address the content-type and expandContext interaction, this is
>> fine.
> 
> As said above, I think that's already addressed but I'll wait for your
> confirmation before making any changes.
> 
> 
> 
> --
> Markus Lanthaler
> @markuslanthaler
> 
>

Received on Tuesday, 3 September 2013 15:13:48 UTC