Re: Testing documentLoader and missing documentation for RemoteDocument

On Sep 3, 2013, at 5:27 AM, "Markus Lanthaler" <markus.lanthaler@gmx.net> wrote:

> On Sunday, September 01, 2013 12:15 AM, Gregg Kellogg wrote:
>> In considering how to test the documentLoader option, it seems to me
>> that we never state the purpose of the contextUrl member of the
>> RemoteDocument dictionary which is provided through the promise. It
> 
> You are right. The documentLoader was introduced quite late in the process
> so this is probably on oversight.

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.

>> seems to me that a processor MUST act as if the contextUrl was provided
>> as the expandContext option, however this isn't stated anywhere in the
>> document. Presumably, a step would be added, for example in the
>> "expand" description:
>> 
>> (between steps 2 and 3): If the documentLoader option is specified,
>> then the result of dereferencing input either results in an error, or
>> in a RemoteDocument. If the RemoteDocument includes a contextUrl, use
>> it as the value of the expandContext option, unless such an option is
>> specified.
> 
> I would propose a slightly different approach. Conformant JSON-LD
> *processors* not only have to use the documentLoader in the three API
> algorithms, but also anywhere else. Thus, I would propose to include the
> following text right under Methods [1]:
> 
> [[[
> 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.

>> Also, the IRI of the currently being processed document (used to set
>> the base IRI of the active context) should come from RemoteDocument.
>> This should be equivalent to simply using documentUrl as a default
>> value of the base option.
> 
> The base is set when the active context is initialized (step 3). I clarified
> that in the text I proposed above.
> 
> 
>> Creating tests for documentLoader requires some special tests, possibly
>> indicating that we should create a document-loader-manifest. To make
>> this work, we'll need to create some .htaccess entries to exercise the
>> variations on the document loader.
>> 
>> document-loader-0001: return input with no link header, content-type
>> application/ld+json -- normal document processing for ExpandTest
>> document-loader-0002: return input with no link header, content-type
>> application/json -- normal document processing for ExpandTest
>> document-loader-0003: return input with no link header, content-type
>> application/jldTest+json -- normal document processing for ExpandTest
>> document-loader-0004: return input with no link header, content-type
>> application/jldTest -- expect "loading document failed" error
>> document-loader-0004: return input with no link header, content-type
>> application/ld+json and status 301 redirecting to another document --
>> normal document processing for ExpandTest from referenced document,
>> using documentUrl as base for expanding document-relative IRIs.
>> document-loader-0005: same as -0004 with status 303.
>> document-loader-0006: same as -0004 with status 307.
>> document-loader-0007: same as -0004 with status 404 -- expect "loading
>> document failed" error
>> document-loader-0008: return input with link header with rel
>> <http://www.w3.org/ns/json-ld#context> and reference to a context
>> document, content-type application/ld+json -- normal document
>> processing for ExpandTest. Specified context is not provided to API,
>> and not used for expanding the input document
>> document-loader-0009: return input with link header with rel
>> <http://www.w3.org/ns/json-ld#context> and reference to a context
>> document, content-type application/json -- normal document processing
>> for ExpandTest. Specified context is provided to API, and used for
>> expanding the input document
>> document-loader-0010: return input with link header with rel
>> <http://www.w3.org/ns/json-ld#context> and reference to a context
>> document, content-type application/jldTest+json -- normal document
>> processing for ExpandTest. Specified context is provided to API, and
>> used for expanding the input document
>> document-loader-0011: return input with multiple link headers with rel
>> <http://www.w3.org/ns/json-ld#context> and reference to different
>> context documents, content-type application/json -- results in
>> "multiple content link headers" error.
> 
> 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.

>> It would be great if someone else wanted to take on creating such
>> tests.
> 
> I will try to create the tests you outlined above later today. Let me know
> what you think about the text I proposed above and I'll update the spec as
> well.

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.

If you address the content-type and expandContext interaction, this is fine.

Gregg

> [1] http://json-ld.org/spec/latest/json-ld-api/#methods
> 
> 
> --
> Markus Lanthaler
> @markuslanthaler
> 
>

Received on Tuesday, 3 September 2013 14:22:30 UTC