RE: Testing documentLoader and missing documentation for RemoteDocument

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.

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


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


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


[1] http://json-ld.org/spec/latest/json-ld-api/#methods


--
Markus Lanthaler
@markuslanthaler

Received on Tuesday, 3 September 2013 12:28:29 UTC