RE: Testing documentLoader and missing documentation for RemoteDocument

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.


--
Markus Lanthaler
@markuslanthaler

Received on Tuesday, 3 September 2013 17:16:49 UTC