LoadDocumentCallback isn't passed into the algorithms that use it

[jyasskin]

https://www.w3.org/TR/json-ld-api/#algorithm uses a LoadDocumentCallback in two places, but its interface doesn't say any such callback should be passed in.

[gkellogg]

The document loader is provided as an API option, and the API options are considered to be generally accessible to the algorithms. This is described in terms of the LoadDocumentCallback which is considered a global for the algorithms, but it either uses a default implementation, or that specified from the documentLoader API option.

[jyasskin]

So if another specification, like https://www.w3.org/TR/vc-data-integrity/#verify-proof, wants to parse JSON-LD, should it go through the API rather than the algorithms?

[gkellogg]

The documentation on documentLoader does specify that the built-in document loader is used by default, so I think this is already taken care of.

documentLoader
The callback of the loader to be used to retrieve remote documents and contexts, implementing the LoadDocumentCallback. If specified, it is used to retrieve remote documents and contexts; otherwise, if not specified, the processor's built-in loader is used.

[jyasskin]

In places where the spec wants to refer to documentLoader and use its defaults, it should use that term instead of LoadDocumentCallback.

But that change doesn't explain to other spec authors how they should override the default. If they need to go through the API instead of directly calling into the algorithms as https://www.w3.org/TR/vc-di-eddsa/#transformation-ed25519signature2020 tries to do, this specification should have a section that says that.

[gkellogg]

Summary: Algorithms use the term LoadDocumentCallback when they should be using the documentLoader (an instance of LoadDocumentCallback), which as part of the API is available to algorithms.

[gkellogg]

But that change doesn't explain to other spec authors how they should override the default. If they need to go through the API instead of directly calling into the algorithms as https://www.w3.org/TR/vc-di-eddsa/#transformation-ed25519signature2020 tries to do, this specification should have a section that says that.

As the JSON-LD API is defined via its WebIDL entry points, I don't think it's the responsibility of this spec to describe how specifications referencing the algorithms directly should handle this. The algorithms always presume they're being called in the context of the API. While it is possible to access the algorithms directly, it is probably more the responsibility of a spec doing such a direct reference to define the envelope of that call. If there are omissions in the algorithm descriptions, we can certainly address that.

The summary above is the change I think is warranted.