Please note that the JSON schema eco-system is still evolving.... Apparently, after over a year of draft-7 of the JSON schema, it looks like draft-8 will be arriving soon. That may change some of the concerns that we have.
Anyway, on our working call, I noted that the JSON schema specification has properties to contribute to documentation. Specifically, it has "title", "description", and "examples". I suggested to Omar that perhaps, before rushing to try to write up a specification document for the JSON version, we should see how well we can produce documentation directly from the JSON schema itself.
Exploring that question hasn't been quite as happy a journey as I had hoped. Some of the challenges have to do with the immaturity of the tools (the json schema spec changed a lot, for quite some time, leaving tools to catch up), and some has to do with the properties of the specification itself.
For the latter constraint, here's an example. Currently, to specify a property as a non-empty string, the schema committed in our repository reads:
"text": {
  "$ref": "#/definitions/non_empty_string_t"
},
What we'd like to do is something like this (for the "text" property, under "full_product_name"):
"text": {
  "title": "a user friendly name for a particular product release",
  "description": "Can be just the full name of the product, plus the version number, or, if the vendor provides it, an informal name for a specific release",
  "example": ["Ubuntu: Cosmic Cuttlefish"],
  "$ref": "#/definitions/non_empty_string_t"
},
See that "$ref" at the end - that refers to a type definition that makes this a string of len() > 0.
Except there's this, from the JSON schema spec,
section 8.3: "All other properties in a "$ref" object MUST be ignored". This means that the documented definition of the "text"Âproperty won't work, because the "title", "description", and "example" fields are suppose to be ignored when the "$ref" is there. I'm guessing the schema authors chose this route - it eliminates the possibility of collision, and then questions about which takes priority. So I don't anticipate this restriction changing with draft 8.
What does this mean for us? The straightforward thing to do is simply change the definitions:
"text": {
  "title": "a user friendly name for a particular product release",
  "description": "Can be just the full name of the product, plus the version number, or, if the vendor provides it, an informal name for a specific release",
  "example": ["Ubuntu: Cosmic Cuttlefish"],
  "type": "string",
  "minLength": 1
},
I'm going to go through and see if I can add documentation corresponding to this approach.
---------
You may be wondering - how did I hit this problem in this little bit of obscure JSON schema?
I went looking around for tools to produce HTML from JSON schema. That turned into an adventure down a particularly large rathole. If you want HTML, the guess is that you also want a "theme" for your HTML. And there are lots of choices about how to produce the HTML (tables vs. div, span vs p, etc.). And then, are you going to be using the HTML in conjunction with a server - can it be dynamic? So - yuck - lots of aesthetic and operational choices to make that have nothing to do with making the content of the schema accessible. Fortunately, I remembered looking at this problem before, wondering how to simplify. Perhaps output to Markdown? Ding, ding! We have a winner. "
jsonschema2md".
I used this tool, and discovered that it doesn't work with internalÂreferences (such as "#/definitions/non_empty_string_t"). Since I determined, from reviewing the specification, that restriction may not get in the way of our use case anyway, this may not be a big problem. But there will still be one or two places where it is a problem. We may either need to fix the bug that blocks the internal references, or deal with a little bit of copy & paste to create workable documentation directly from the json-schema.
Those are my notes, for now.
Eric.
P.S. One last thought, if you've gotten this far. Even if we end up not liking the jsonschema2md output, it still helps in a few ways. One is that it gives us a baseline upon which we can improve, and helps to focus on the content of our documentation, not the presentation. Two, it provides an example of the data model that other people have found useful when documenting JSON. We might find, for example, that we could fork the tool, and instead of having it output the markdown directly, it could output a data model for JSON schema documentation. We could then use that data model to generate the documentation of our choosing - markdown, HTML, add SVG imaging, etc.
More work than I would prefer, but it gives us a way forward that is probably significantly faster than trying to invent it ourselves.