Recommend a way for dependent specs to call into this one, that's not WebIDL

[jyasskin]

In w3c/vc-di-eddsa#100 (comment), the Verifiable Credentials WG rejected the idea of depending on the JSON-LD spec via its WebIDL interface. To be useful, "library" specifications need a clear way for other specs to depend on them, which those depending specs are willing to use. I think that means that JSON-LD needs to produce such an acceptable interface by the time the AC votes to publish the next version of its REC.

[gkellogg]

WebIDL is how we describe the data structures, including Options, as well as the envelope for invoking the core algorithms. I don't see a way to separate out the data structure bit from everything else without inventing new mechanisms for describing these.

Perhaps we can add some informative text to the WebIDL section about alternate ways to invoke the algorithms, which don't depend on promises and other IDL-specific details. This is pretty much how my Ruby implementation works, as it does not bring in a separate Promise/WebIDL layer.

[jyasskin]

https://infra.spec.whatwg.org/#structs provides a way to describe data structures that doesn't imply a Javascript API. You can see a spec describing how to call itself in https://fetch.spec.whatwg.org/#fetch-elsewhere, where the options are in the request struct.

[BigBlueHat]

@jyasskin are there W3C specifications you've seen that do this the way you have in mind? It would be helpful to see a finished product (or even one in progress) that matches your expectations. Thanks!

[jyasskin]

https://w3c.github.io/hr-time/#sec-tools doesn't define structures, but it provides an interface like this.

https://w3c.github.io/reporting/ doesn't have the nice "how to call into me" section, but it defines structures and algorithms that are called from other specs. (Some of those other specs, like https://wicg.github.io/document-policy/#algo-is-value-compatible-or-report, call into section names instead of definitions, which prevents tools like https://dontcallmedom.github.io/webdex/ from tracking the full reference graph, but you can see the overall idea.)

WebIDL itself uses this style, despite not living in the W3C. The algorithms it defines, like https://webidl.spec.whatwg.org/#invoke-a-callback-function, tend to be aimed at translating between Javascript and spec types, which is another argument against using it as the interface between specs.

And I'd still encourage you to look at all the W3C specs that call into WHATWG specs as potential models: https://dontcallmedom.github.io/webdex/f.html#fetch%40%40fetch%25%25dfn

[iherman]

Another model that can be looked is the DID Resolution spec's usage of INFRA for the interface definitions: see, e.g., https://www.w3.org/TR/did-resolution/#resolving-algorithm.

[w3cbot]

This was discussed during the #json-ld meeting on 12 February 2025.

View the transcript

w3c/json-ld-api#627

<gb> Issue 627 Recommend a way for dependent specs to call into this one, that's not WebIDL (by jyasskin) [ms:future-work] [needs discussion]

bigbluehat: we discussed this last call. I asked Jeffrey for more examples, which he provided.
… ivan, you pointed out that DID-Resolution uses INFRA instead of WebIDL.
… The main remaining issue is the amount of editorial work.

pchampin: we could maybe automate the WebIDL to INFRA conversion?

bigbluehat: or have an AI do that...

---

[w3cbot]

This was discussed during the #json-ld meeting on 26 February 2025.

View the transcript

w3c/json-ld-api#627

<gb> Issue 627 Recommend a way for dependent specs to call into this one, that's not WebIDL (by jyasskin) [ms:future-work] [needs discussion]

bigbluehat: It was non-normative in the RDF WG days, but we worked it harder into 1.1.
… It comes down to who is going to take this on as an action. I don't think the TAG will continue to allow us to use WebIDL.
… It's not clear what the alternative is.

bigbluehat: I agree that it's not really worth doing something different. WebIDL is typically about browsers, but the TAG told us to use it for 1.1 and changes were made to isolate the context from browsers.
… I'm not sure how big the ask was to switch to using INFRA terms, and it's hard to know the net benefit.
… I don't really see the benefit either. We already have places in the spec that use the WebIDL type system.
… It's a historic artifact, and we will continue to provide context to the data structures.
… He pointed to VC WG discussions about "calling into the JSON-LD spec".
… The concern is in the EDDSA spec (referenced in the issue).
… The conversation has similar confusion. If EDDSA had linked to WebIDL it may cause issues with the TAG.

pchampin: I delved into these discussions I think the commenter has conflated the JSON-LD API with some global configuration.

<pchampin> w3c/json-ld-api#580 (comment)

<gb> Issue 580 LoadDocumentCallback isn't passed into the algorithms that use it (by jyasskin) [spec:editorial] [ErratumRaised] [Editorial] [class-2]

pchampin: In the VC issue he was concerned about parameters about the documentLoader, defined via the API (WebIDL). But, you could abstract away the API and the fact that it is expressed in WebIDL.
… WebIDL is there for historical reasons. We can clarify that using the API doesn't necessarily mean using WebIDL.

---

[jyasskin]

To be clear, I don't personally mind a non-browser "library" spec like JSON-LD defining its interface in WebIDL. The critical thing in my mind is that it defines an interface that its callers are willing to use. If its callers (like VC) wind up calling into "internal" algorithms, and especially if they forget to set up state that those algorithms expect, that increases the maintenance burden on both sides and the risk of bugs and interoperability problems.

I'm also not speaking for the TAG here. My thoughts will obviously inform the TAG's opinion as long as I'm on it, but we haven't discussed this issue as as group, and there's a plausible argument that specification style might be outside the TAG's domain.