Ad for the Bokeh specification, there’s sort of two levels to think about it:
Organizing level
This is the fact that at the top level, all Bokeh objects look like this:
{
"attributes": {
....
},
"id": "6956",
"type": "Range1d"
}
This has not changed in a very long time, and is unlikely to ever change. I suppose it could be documented more prominently. A similar statement holds for the general “shape” of Document
. Where there is more variability is the individual “object” level.
Object Level
This is the contents of that attributes
block above. This is a key-value dict that holds all the Bokeh properties of the Bokeh model. E.g. a Range1d
has start
and end
properties, so:
{
"start": 0,
"end": 10,
...
}
So the question is where is the ground truth for what that set of properties is? Currently, the Python API is the ground truth, so the Python reference guide is the document for exactly what goes in attributes
.
We also have continuous tests to ensure that the BokehJS classes agree 100% with this Python “ground truth”. So Python and JS are guaranteed to be in sync with each other. What we don’t have, is an independent, declarative specification outside of both Python or JS. We do have a tool that can dump an ad-hoc JSON blob that describes the total collection of Models and their Properties, but that “spec” is derived from the Python source.
We could imagine a situation where some JSON spec is itself primarily the “ground truth”, and then do code generation everywhere based on that spec. E.g. the way REST models APIs are auto-generated from Swagger files. In that world, Python descends from its special place of prominence and is just another language that implements a binding for the “Bokeh spec”. There are definitely benefits to this approach, but also costs, like anything.