Re: Testing documentLoader and missing documentation for RemoteDocument

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

> On Tuesday, September 03, 2013 5:13 PM, Gregg Kellogg wrote:
>>>> [[[
>>>>> 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.
> 
> OK, I've added the text to the spec:
> 
> https://github.com/json-ld/json-ld.org/commit/e642063dc06214a78206b0fa1dea04
> 6dada4a468
> 
> [...]
>> 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.
> 
> Right, but JSON-LD implementations are not required to implement the
> documentLoader option - only JSON-LD processors (implementations that also
> implement the specified API). Thus I proposed to simplify it by moving it
> directly into idltest.

We discussed this on the call last week: http://json-ld.org/minutes/2013-08-27/#topic-3

The problem with the IDL tests is that they aren't useful for showing implementation across multiple platforms, only a JavaScript implementation, for which only one exists. We discussed adding a "useDocumentLoader" option with a specification of what such a documentLoader must do (actually, it doesn't really need anything special). This allows us to test that an implementation properly responds to the results of having invoked a dcoumentLoader:

*If the documentLoader option is used, errors MUST result in the Promise being rejected with a JsonLdError with one of two different codes.
*If a document of type application/ld+json is retrieved, and there is a Link Header with rel=http://www.w3.org/ns/json-ld#context, the contextUrl MUST be empty. The only way to test this is to verify that such a context is not, in fact, loaded.
* If there are multiple link headers, it must raise JsonLdError with multiple context link headers.
* loading a document MUST follow HTTP redirects

This is why we need to provide minimum implementation requirements for a test-runner documentLoader so that we can trigger these options.

It's interesting that these requirements are only really specified for the documentLoader option, and not as native behavior of the API methods. Perhaps it would have been better to say that, in the absence of a documentLoader option, an API implementation MUST behave as if it is set to an internal loader satisfying the requirements of a LoadDocumentCallback, and then encapsulate all these requirements in one place, rather than in each API method.

Gregg


> --
> Markus Lanthaler
> @markuslanthaler
> 
>

Received on Tuesday, 3 September 2013 16:16:07 UTC