Capture specs in a machine readable format?

[bollwyvl]

This is a very exciting project!

Beyond a textual description, a canonical machine-readable format would be very useful. The current issue, which I have experienced first-hand, is that the reference implementation can change rather suddenly, leaving external repositories, metadata tools, etc. to be rather confused when something changes. A good example of this is the Debug Adapter Protocol which treats its schema as the source of truth, and generates everything from that.

A go-to for things that ever end up on-disk or on-wire as JSON is JSON Schema (specifically, in 2020, draft7, as draft8 is causing some heartache for some implementers). At a minimum, it can be used directly by implementations at runtime to validate some input in just about any language, which can be extended with generated type stubs.

Beyond this, schema can be leveraged to generate robust property-based tests or pretty professional-looking reference docs.

Yet another interesting angle is, given enough representative examples, a schema can be synthesized (even partially).