Add JSON Schema renderer for ReSpec

[msporny]

This PR adds a JSON Schema renderer for ReSpec. This includes automatically (but conservatively) generating normative specification text from the JSON Schema with the goal of ensuring that the normative statements in the VC API specification and the JSON Schema are kept in sync. This will be a work in progress -- JSON Schema is complex and the language is inconsistent -- but this is good enough for a first cut to see if folks want to pursue this route. The alternate route is MANUALLY keeping all the JSON Schema and ReSpec in sync w/ one another.

An example of the output of this ReSpec plugin is provided below:

---

Preview | Diff

[mprorock]

awesome step in the right direction - i say we get it in

[mavarley]

Excellent! Agree with @mprorock , let's get this integrated.

[dlongley]

Agree that this is a good first cut. I haven't had time to look and see if there is any additional / outside tooling with good test coverage we could use here to reduce the maintenance burden.

[OR13]

seems like a waste of time to do this in respec, given its automatically handled better in other tools, but I won't stand in the way of it.

[msporny]

@OR13 said:

+1 To themeing an existing tool, and not reinventing wheels.

@mprorock said:

Just putting a theme together for you know in a config together for something like redoc and have it render out as you know you know with ReSpec boundaries around it etcetera right and just insert that stuff as header and footer in the templates... I mean that that is an option and then we're not worrying about the renderer you know you know like interpreting and rendering this stuff right.
https://spec.openapis.org/oas/v3.1.0
https://github.com/OAI/OpenAPI-Specification/blob/main/.github/workflows/respec.yaml

I'm trying to chase this down and going through examples that were pointed to on the call yesterday. It looks like the JSON Schema sections of the OAS specification are not auto-generated and that they have instead hand edited the JSON Schema in the markdown-formatted ReSpec input file and then hand synchronize with the specification. That is, the OAS spec is hand-written markdown, and hand-translated JSON Schema... there is no auto-generation going on AFAICT.

History of hand-edited changes to JSON Schema tables in OAS ReSpec input (markdown file):
https://github.com/OAI/OpenAPI-Specification/commits/main?after=a1facce1b3621df3630cb692e9fbe18a7612ea6d+34&branch=main&path%5B%5D=versions

Example of hand-edited JSON Schema table:
OAI/OpenAPI-Specification@23ea128

I will also point out this note from the OAS spec:

As a reminder, the JSON Schema is not the source of truth for the Specification. In cases of conflicts between the Specification itself and the JSON Schema, the Specification wins. Also, some Specification constraints cannot be represented with the JSON Schema so it's highly recommended to employ other methods to ensure compliance.

To put it another way, even the OAS folks are hand-synchronizing the JSON Schema with the OAS Specification.

Granted, I only spent about 15 minutes looking, so perhaps I'm missing some build step in there somewhere. What am I missing? Have you guys actually seen this working, or were you guessing on the call yesterday?

I'll keep going through the other links later today/tomorrow in an attempt to avoid doing this work, but at this point, I'm not seeing something we can reuse.

[OR13]

Checkout this automatically rendered version of an OAS spec... it even has "try it out" features.

https://api.did.actor/docs#get-/credentials/-credential-id-

Here is the same thing again:

https://w3c-ccg.github.io/traceability-interop/openapi/#get-/did.json

My point was that instead of making respec plugins, we could be just using off the shelf tooling, and focusing on defining the actual API... Call time spent discussing respec plugins, could be used to discuss api features instead.

I'm not objecting to the PR, I just know how valuable every little contribution (from people who open pull requests) is to the W3C CCG is, and pointing out that our time could be better spent.

[msporny]

Call time spent discussing respec plugins, could be used to discuss api features instead.

I don't expect we'll spend much, if any, future call time on this feature. It'll just be "something that's there", and I'll silently fix bugs as they come up, much like I do for the other respec tooling we use.

Checkout this automatically rendered version of an OAS spec... it even has "try it out" features.

Yes, but that's what @mprorock's PR does -- those renderings. Those are not, however, ReSpec renderings of HTTP API endpoints:

https://www.w3.org/TR/webdriver/#get-current-url

Granted, the HTTP endpoint documentation for Web Driver (as an example) leaves much to be desired. This group has decided that they want to define the API in OAS and JSON Schema, which is fine, but in order to do that AND produce something that looks familiar to W3C Members, translating it to ReSpec is the easiest path we have. If we just point W3C folks to an OAS redoc rendered file, it'll raise eyebrows, which will then kick off a whole thread on "Well, is OAS a valid specification file format at W3C?" -- and that's a debate I'd like to avoid. To put it another way, if it takes me a couple of weekends to losslessly translate an OAS file into W3C spec language, I'd rather spend my time there than arguing with the W3C Advisory Committee and Process wonks.

I'm not objecting to the PR, I just know how valuable every little contribution (from people who open pull requests) is to the W3C CCG is, and pointing out that our time could be better spent.

I welcome a better solution to the problem above. I realize solving that problem is not everyone's priority, but it will eventually land on my plate and I'd rather get out in front of it than let is side-swipe the group. In any case, this is probably the first and last time we'll use call time on this particular topic... we have agreement from the group to proceed, and that's all I need to improve this over time.

At present, we have all the things that everyone wanted:

1. Redoc, Rapidoc, and Swagger renderings of the OAS files (auto-generated on every commit).
2. ReSpec renderings of the OAS files (auto-generated when the spec is viewed in a browser).