search

w3c / at-driver

AT Driver defines a protocol for introspection and remote control of assistive technology software, using a bidirectional communication channel.
https://w3c.github.io/at-driver
Other
32 stars 4 forks source link

Script to generate JSON Schema from CDDL #23

Open zcorpan opened 2 years ago

zcorpan commented 2 years ago

In https://github.com/w3c/aria-at-automation/pull/19 I wrote a script to extract the CDDL fragments from index.bs and put them into two CDDL files (one for the remote end definition and one for the local end definition). I also manually converted them to JSON Schema.

The script also imports the cddl npm package, which is able to parse the CDDL. My idea was that it should be possible to iterate over the parsed AST and from that generate equivalent JSON Schema, such that the output is the same as the manually-crafted JSON Schemas (modulo formatting).

This is lower priority than tackling the MVP milestones in the roadmap #15, but still seems worthwhile since manually maintaining the JSON Schemas seems error prone at best.

jugglinmike commented 1 year ago

I agree that manual translation is not a viable option.

That said, the "cddl" npm package doesn't seem viable at this time, either. From the project's documentation:

Note: this is work in progress, feel free to have a look at the code or contribute but don't use this for anything yet!

We've already experienced friction from neglecting this warning when we had to change our use of CDDL to accommodate the parser's limitations. I doubt that we'll have a better experience if we build code on top of that module in its current state.

On the other hand, the "cddl" Rust crate seems more mature. It's documentation is a little cautionary:

While there are some examples of this crate being used in production, careful consideration should be made prior to using this crate as such.

...but the WebDriver BiDi proposal are among its current users.

My search for alternatives has only turned up a couple other CDDL parsers (one in Java and one in Ruby), but both appear to have been decommissioned.

I think that if we want to offer a JSON Schema representation, automating its generation with the "cddl" Rust crate is the way to go.

zcorpan commented 1 year ago

A semantic difference between JSON Schema and CDDL to keep in mind when converting is, similarly to W3C XML Schema vs. RELAX NG, the former starts with "everything is allowed" and you need to disallow things, and the latter starts with "everything is disallowed" and you need to allow things. This can make it tricky when combining schemas and you don't want to allow arbitrary keys for an object, for example.

christian-bromann commented 1 year ago

Hey folks, it took a while until I got the cddl NPM package back from my former employer and I started to continue working on the parser again to help the Browser Testing and Tools WG validate their CDDL interface. I started work on a compiler into TypeScript. Compiling the AST into a JSON Schema should be much easier given it is basically just a restructured AST. I am not sure how much time I get to spend on this, given it is not my primary job and more side hobby. If the current CDDL Rust package does the job, go with that one.

lolaodelola commented 8 months ago

@jugglinmike is this still relevant?

jugglinmike commented 8 months ago

@lolaodelola Yup!