Convert main specification to YAML format
wshayes opened this issue · 6 comments
It seems weird to define a JSONSchema in YAML, but the advantage is
- it is easier to read
- it translates back to the JSON with no problems
- most importantly - you can add comments!
My proposal is to make the main editable format of the JSONSchema in YAML and use a build script to convert it to JSON and validate it. json2yaml (python module/cli) does a good job of maintaining order of keys when converting back and forth.
This is a great idea. YAML is readable, at the expense of bytes (spaces, line feeds), so giving users the choice is important.
Should the name change? We could incorporate other formats such as protocol buffer schemas for binary representations.
Will YAML support be a library authors responsibility?
I'm suggesting YAML as the format to author in, but we would provide a JSON version of it for computers to use (JSON is much faster to parse than YAML). YAML since it's readable and allows comments - and it's a simple conversion to JSON everytime it's updated using a CI tool.
That makes sense to me. 👍
Which issue can I help with?
Excellent suggestion. I'm about to build a tool that uses a tree structure. Having extensively used YAML to document rest APIs in the Swagger editor I see how this will be intuitive. I will like to be a part of this journey. Can I join?
Yes - we'd love the help!
Think the JSON spec is fine and directly usable by most. Closing this.