Re: Testing documentLoader and missing documentation for RemoteDocument

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

> On Tuesday, September 03, 2013 6:16 PM, Gregg Kellogg wrote:
>> On Sep 3, 2013, at 8:47 AM, Markus Lanthaler wrote:
>>> 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:
> 
> Yes I remember. But the feature we are testing here depends on DOM Promises.
> I doubt any non-Javascript will implement them. If it does, it MUST also
> pass all WebIDL tests. So that shouldn't be an issue.
> 
> 
>> *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.
> 
> What you are describing here apply to the documentLoader but the JSON-LD
> processor's built-in behavior. It's up to the user to specify what the
> documentLoader does. The processor however must handle the results in a
> consistent way. That's an API thing IMO.
> 
> 
>> It's interesting that these requirements are only really specified for
>> the documentLoader option, and not as native behavior of the API
>> methods.
> 
> They are specified for each method.
> 
> 
>> 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.
> 
> The whole point of the documentLoader is to be able to override that
> behavior. A developer can implement whatever he finds useful. For example,
> he might decide to rewrite JSON responses by adding a pre-configured context
> or it might transform Microdata JSON or RDF/JSON to JSON-LD on the fly.
> That's completely valid behavior.

It would have been useful to voice the opinion more forcefully when we had the discussion on the last call. So, you're suggesting now that we remove the useDocumentLoader test option and not do any tests specifically invoking a runtime defined documentLoader?

Gregg

> --
> Markus Lanthaler
> @markuslanthaler
> 
>

Received on Tuesday, 3 September 2013 17:38:46 UTC