Investigate defining a schema for faucet.yaml & gauge.yaml
Opened this issue · 2 comments
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:
- Easy to validate for parsing issues (and automatically generating nice error messages)
- Easy to autogenerate documentation
- 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.
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.
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.