generic: add schema for config.yml

[ltalirz]

Add JSON schema for validating config.yml

The config.yml is automatically validated against the schema when running build.sh. A "modeline" is added to the config.tpl.yml, which points to the schema and provides automatic validation in VSCode with the "YAML" extension by RedHat.

[ltalirz]

Hey @xpillons , here is a draft for validating the config.yml via a JSON schema
It works directly in VSCode with the YAML extension, just try it on the config.tpl.yml.

Couple of points to decide/fix

• validation currently fails (largeviz3d is actually too long a name)
• is JSON schema OK or do you prefer to go with a YAML schema (to my understanding, YAML schema is a bit less widely used + not sure whether VSCode will support it)
• should the schema go in the top level or, e.g. under /toolset? Putting it in a subfolder helps to unclutter the top level, but might make it less obvious for developers that the schema needs to be updated alongside the config.tpl.yml
• the schema currently contains a few fields specific to our setup (e.g. workstation VMs). I can remove this

cc @matt-chan

[xpillons]

@ltalirz this is a great start.

• unfortunately largeviz3d is used in several places and changing it will introduce breaking changes. Is there a way to have av exception in the schema ?
• JSON schema is perfect
• It's fine having the schema at the root in the same place that the config.tpl.yml file

I would add an option in the build.sh to skip schema validation, I'm sure there are several cases we haven't think of, and this would be useful.

[ltalirz]

Hi @xpillons, thanks for the quick review; I've addressed your comments, the remaining question would be whether to remove any mention of workstation from the schema (just let me know).

[xpillons]

@ltalirz please build the schema based strictly on config.tpl.yml as it will be confusing otherwise.

[xpillons]

@ltalirz what would be the process to update the schema ? is there a tool to do this ? if so can instructions be added ?

[ltalirz]

@ltalirz what would be the process to update the schema ?

For the first draft I programmatically inferred the schema from the existing yml file and then manually added descriptions, constraints, etc.

I believe for minor changes to the config.tpl.yml it would be easiest to just edit the schema manually, it's quite straightforward and VS Code already knows all the allowed fields in JSON Schema, which makes it even easier.

One aspect you may want to think about is whether the in-line documentation can eventually be removed from the config.tpl.yml since it is present in the schema and is accessible via mouse hover in VS Code:

Having it in the schema seems important to be able to provide good error messages; this should also make it straightforward to reuse in a GUI on the Azure Marketplace.

At the moment this information is somewhat duplicated (but maybe ok for the time being).

is there a tool to do this ? if so can instructions be added ?

I guess this would call for a new section of the az-hop documentation aimed at developers rather than admins?

[ltalirz]

P.S. The schema can also be used to define default values transparently. I've not yet started doing that.

[xpillons]

ok, got it. In fact not all customers are using VSCode, hence docs in the template file directly. And yes we should have a developer section in the doc.

[xpillons]

I approve this first release, we can work on adding more constraints in the future