Investigate defining a schema for faucet.yaml & gauge.yaml

[gizmoguy]

There are systems like https://github.com/alecthomas/voluptuous which let you programmatically define a YAML configuration schema.

Defining our configuration via a schema that can be validated against would give us some benefits:

1. Easy to validate for parsing issues (and automatically generating nice error messages)
2. Easy to autogenerate documentation
3. Easy to deprecate and change options

I suggest voluptuous as that's what https://github.com/home-assistant/core uses and they seem to have good success, however there might be better systems.

[shivarammysore]

One suggestion that I can add to a schema definition is use of OpenAPI The advantage with this model is that we can easily use tooling built for this.

[shivarammysore]

A couple of notes from our experience that may be helpful: Overloaded Keys A key within faucet.yaml should not be overloaded from a schema perspective. For example, there is at least one faucet.yaml overloaded key - vlans. It is a top-level index of a network’s vlan objects; and, within a routers item it is an array of vlan names.

Faucet Index Objects Faucet.yaml uses index objects where keys are network-specific identifiers for faucet-defined semantics. From a human ease-of-use perspective this seems fine; however, from a semantic perspective it is a problem.

This design prevents these index keys from being properly typed. Instead, faucet should consider using arrays of faucet defined objects that used faucet-defined keys to specify network typed values.