Automatic creation of JSON Schema

[adrianholovaty]

In this pull request, I've improved our docs system to automatically create a JSON Schema from the data in the docs system.

This means, whenever we add or change things in MNX, we'll get an automatically updated, machine-readable JSON Schema "for free."

You can view the generated JSON Schema here, as it stands on this branch:

https://cdn.githubraw.com/w3c/mnx/json-schema/docs/mnx-schema.json

It's linked-to from the left sidebar of each docs page ("Raw JSON Schema"):

An implementation note: this automatically creates $defs for any object that's referenced more than once. Otherwise, it puts the various definitions inline/nested. I figured this approach would result in the best readability, but the logic is easy to tweak if needed.

I tested it against one of our example MNX documents, using an online JSON Schema validator, and it validated with no errors. I still need to test against all the other MNX examples.

I'd like to thank @paul-bayleaf and his work on #308 for laying the groundwork for this! I used his manually created JSON Schema document as a reference, and this project would have taken significantly longer to implement without that.

If anybody has feedback on this JSON Schema, please leave a comment!

[paul-bayleaf]

Excellent! I can confirm that your schema validates all the examples with the exception of Orchestral layout and System layouts, which fail by design, as discussed in issue #306.

I think it is important that where possible a schema should validate values, e.g. where a property is constrained to a pre-defined set of values, or where an integer is constrained in range. i did this in my schema using the "enum", "minimum", "maximum" etc features. But these are absent from your schema.

e.g. line 243 "positive-integer": { "type": "integer" },

add a constraint "positive-integer": { "type": "integer", "minimum": 1 },

line 705 "grace-type": { "type": "string" },

enumerate the allowed values "grace-type": { "type": "string", "enum": ["make-time", "steal-following", "steal-previous"] },

JSON Schema Validation: A Vocabulary for Structural Validation of JSON

[adrianholovaty]

@paul-bayleaf Excellent, thanks for testing! That's a great point about using enums and stronger types for validation. Let me go ahead and merge this as-is, and I'll create a separate GitHub issue for those further improvements (in the interest of moving this forward and keeping some momentum).

[adrianholovaty]

This has been merged, as of 5bf366d.

[adrianholovaty]

@paul-bayleaf Just a heads up — I've expanded our automatically created JSON Schema to include enums where appropriate. See 07ff9a789e, 20fd5b05c and dfd0aa368a.