JSON Schema 2020-12 definition for Arazzo descriptions

[jeremyfiel]

closes #176

There are four pending issues related to finalizing this draft
#223
#222
#221
#220

[frankkilcommins]

@jeremyfiel thanks for the initiative here. There is already a draft PR #198 from @LasneF for #176. Can I encourage you both to work together and consolidate under a single PR for review?

[LasneF]

Feedback that apply globaly :

• should we endforce Id syntax knowing that it is just a recommendation
• shoud we enforce array to have at least one element vs the syntax [] that is good as well as explicit

[frankkilcommins]

LGTM - Thanks @jeremyfiel

[frankkilcommins]

@jeremyfiel could you add a schema.json as part of this too?

[jeremyfiel]

In the OAS repo, I believe they use yaml as the base schema and there is a JSON version generated during the build. Is that something Arazzo repo will replicate? If not, I can a JSON version too.

[frankkilcommins]

I think it's manually maintained - see example: https://github.com/OAI/OpenAPI-Specification/commits/main/schemas/v3.0/schema.json

There's a job that generates JSON examples for YAML examples, but I don't see similar for schemas.

[handrews]

@frankkilcommins we definitely only take PRs on the YAML schemas. The schema publishing process is completely broken, though. See OAI/OpenAPI-Specification#3715. It's been broken for years but there's never been anyone with both the time and ability to fix it. In theory we'll fix it after the patch releases ship but idk who's going to do the work on it.

[frankkilcommins]

@handrews in the interest of simplicity we'll mandate changes on both the JSON and YAML schemas for now.....and time permitting we'll just require one and generate the other.

[ndenny]

Thanks for the work!