Extract CDDL for WebDriver BiDi

[gsnedders]

Currently we have multiple specs defining WebDriver BiDi endpoints; https://w3c.github.io/webdriver-bidi/ itself does, but also https://w3c.github.io/permissions/#automation-webdriver-bidi and https://webbluetoothcg.github.io/web-bluetooth/#automated-testing.

We have some code to extract CDDL from the WebDriver BiDi code, see https://github.com/w3c/webdriver-bidi/blob/3b1939c2380b9ba12cc123cef03c1e3af15fa01d/scripts/cddl/utils.js#L13, and generates three CDDL files ultimately: local.cddl, remote.cddl, all.cddl.

We probably want to pull out all of local-cddl and remote-cddl separately; all is just the union of both of these.

See also: w3c/webdriver-bidi#791

[tidoust]

I'm not sure how to approach the "multiple extracts per spec" need (local and remote for WebDriver Bidi). The crawler generates one extract per spec. At a minimum, we'd need some sort of generic convention to understand what bucket to use for a given definition.

I note that the Open Screen Protocol also defines CDDL. In the case of the Open Screen Protocol, CDDL is actually maintained in a .cddl file that gets converted to an HTML file through a script upon build and imported in the spec (interestingly, the resulting spec does not contain any semantic info that says "this is CDDL").

If we start extracting CDDL from specs, it would be useful to also think about some validation mechanism.

[gsnedders]

(I also guess I maybe should've filed this against reffy rather than webref)

[tidoust]

Another spec that defines CDDL is WebAuthn. There, the CDDL is not flagged in any particulary way (just a <pre>). I don't see other specs in browser-specs that reference RFC8610.

[gsnedders]

I wonder if we need to add an extra class for WebDriver BiDi CDDL?

[tidoust]

That does not change the problem at hand, but just to draw a more complete picture, in an ideal world, authoring tools would also support something like a <pre class=cddl> section that would:

1. Turn on syntax highlighting (CDDL syntax highlighting is already supported in Bikeshed provided one adds highlight="cddl", but does not seem supported by highlight.js that ReSpec uses)
2. Create definitions and auto-link terms, as done in Web IDL blocks, noting that there is no specific definition type that may be used for CDDL terms right now.
3. Allow for the automatic creation of an index at the end of the specification.

For Bikeshed, that's tracked in speced/bikeshed#2072. The issue notes the need to split the index into two (and the need for Webref to extract the CDDL).

[tidoust]

Getting back to this...

@gsnedders What is the use case for the all.cddl file?

It makes sense to me for the crawler to produce local.cddl and remote.cddl extracts. I'm wondering about the rationale for producing the all.cddl extract. Is it useful for implementations, testing purpose, or something else?

[gsnedders]

@tidoust That's a good question; I listed it because it already existed, seemingly from w3c/webdriver-bidi#465.

@OrKoN @jgraham @whimboo do you know?

[OrKoN]

we do use all.cddl to generate TypeScript types and validation code in chromium-bidi. I believe all.cddl helps to avoid duplication of definitions which are marked as both local and remote.

[tidoust]

OK, thanks. If that file is useful, I'll try to re-create it in Webref, then.

While you're all watching, feel free to have a look at speced/bikeshed#2977, a proposal to add CDDL support to Bikeshed.

Support would add autolinking capabilities within CDDL blocks and generate a CDDL index at the end of the spec. Currently, this would generate a CDDL index per module (building on a convention similar to the one used in WebDriver BiDi). In the case of WebDriver BiDi, the CDDL index would thus list two modules, one with the contents of local.cddl and one with the contents of remote.cddl. If you feel that the spec itself should also contain a CDDL index with all definitions, let me know! I'm thinking it could be generated by the crawler otherwise.

Alternatively, it could also contain 3 indexes:

• One with all CDDL definitions that are common to all modules
• One with all local end definitions
• One with all remote end definitions

I'm not sure how to generalize this approach to a spec that defines more than two CDDL modules though (combinatorial explosion), but perhaps it just doesn't make sense for a spec to define more than 2 CDDL modules at once.

[whimboo]

I've a question regarding CI checks when certain specifications are changing their CDDL definitions. Is there a way to actually cross-check if we can still generate the files or if failures occur? It's basically out of our hand what other specifications are doing, and we not necessarily want to see our final CDDL export broken.

[tidoust]

There are two data levels in Webref:

• the main branch contains raw data extracted from specs. That comes with no guarantee whatsoever. If a spec that defines CDDL contains invalid CDDL, that invalid CDDL will be in the main branch.
• the curated branch contains a curated version of the raw data. That branch is only updated when guarantees are met. When guarantees are broken, we patch the data manually to resume updates. Now, we'll need to agree on guarantees for CDDL. I don't really know what "generate the files" means. I suppose that we'll want to run a CDDL validator (cddl-rs?) against the extracts and guarantee that all CDDL extracts pass validation.

[tidoust]

Oh, and there's a third level I completely forgot to mention:

• Updates are manually reviewed on a weekly basis (on average) to release npm packages: @webref/css, @webref/idl, @webref/events. The manual review allows us to catch additional consistency issues that cannot easily be checked automatically. We could envision a @webref/cddl package if that seems useful.