search

w3c / json-ld-api

JSON-LD 1.1 Processing Algorithms and API Specification
https://w3c.github.io/json-ld-api/
Other
77 stars 31 forks source link

LoadDocumentCallback isn't passed into the algorithms that use it #580

Open jyasskin opened 1 year ago

jyasskin commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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 commented 2 weeks ago

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 commented 2 weeks ago

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 commented 2 weeks ago

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 commented 2 weeks ago

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.