Configuration File Schema Validation

[NuSkooler]

It may be nice to have very basic schema validation for configuration files (config.hjson, menu.hjson, etc.).

• Help users identify issues with their configurations
• Ideally something very light
• Must allow for additional entries/sections that are not known to the schema

Configuration files are in HJSON, but this directly converts to JSON internally. It may be enough to work with the JSON.

JSON schema validation resources:

• https://github.com/yusufnb/verify-json - Looks very interesting in that it is extremely light weight and allows custom validators
• https://json-schema.org/ - This spec is quite intense

See also: #280

[louisnorthmore]

This would be useful - would have saved me some time yesterday!

[louisnorthmore]

I might take a look at this later. @NuSkooler How do you see it working? A separate tool to begin with?

[NuSkooler]

@louisnorthmore I haven't put a ton of detailed thought into this, but something like:

• When the configuration is (re)loaded do quick validation
• Possibly an explicit ./oputil.js config validate if that can provide additional benefits.

I like the idea of veirfy-json since it's light weight and allows custom validators.

[NuSkooler]

At this point if it hasn't been picked up yet, I change my stance and suggest JSON schema as it's been the clear winner around JSON... schemas.

Upon validation error(s), writing to stderr and to the log (if possible) should be enough when starting up or hot reloading the config.

[cognitivegears]

Agreed with the overall approach, and this would be fantastic. I know when I was getting started having a broken config was my biggest struggle. The only one I'm not sure about is the last bullet point: "Must allow for additional entries/sections that are not known to the schema" - this would somewhat limit some of the usefulness I think? If someone is trying to debug why a configuration item is not taking effect, etc, this would be easier if there was at least the option to restrict to known elements.

[NuSkooler]

@cognitivegears I think we can validate things that are in the wrong place, and specifics of all known configuration elements, but consider e.g. a custom mod that is not shipped with enig, but wants some configuration from config.hjson. If the user adds a new block in the right area of the config, we won't have a way to really validate the inners. Unless of course we expose a way for mods to supply their schemas -- which feels a little gatekeeping as most people won't know what to do there.

In JSON schema at least, this probably mostly around allowing additional properties in certain blocks.

[cognitivegears]

Well, we could validate something that is missing, but not something that is optional but misnamed. And since there are a lot of optional properties in the enigma conf I feel this could be a problem. Not the end of the world for sure, but how about a slightly different approach:

Add an optional "mods" property at each level containing an array of objects of "any" type. That way, mods are free to add additional properties, they just have to put it under "mods". So like:

matrix: {
    desc: Login Matrix
    art: matrix
    mods: [
        mod1: [
             extendedDesc: This is a longer description for this mod. Or something.
             anotherProperty: true
        ]
        mod2SingleValue: 125
        // ...
    ]
    // ....
}

Since it is validated with the "any" type, it doesn't care or validate what is under the mod (if the mod wanted to validate the values itself with it's own schema it could, but doesn't have to.)

Still "wild west", just a little more "wild west, but stay in your sandboxes." :) Then we could validate everything else.

[NuSkooler]

In menu.hjson, like the "matrix" example above, we can validate the full allowed syntax. I don't think that should be much of a issue. There are some cases such as config blocks within that scope that allow arbitrary per-mod keys, but they are nested enough I think we can take care of them.

Here is what I'm thinking (this example with config.hjson) just to make sure we're on the same page:

// config.hjson
{
  general: {
    // we can validate all this regular type stuff easily
  }

  // example for 'my_mod' wanting config.hjson configuration:
  my_mod: { // we can validate that any "additional" non-official keys here are Objects
    // anything JSON/HJSON is fine here & not validated by enigma itself
  }
}

Another thing we can do, is expose some API(s) that mods can use to easily do their own validation if they want to opt-in.

// menu.hjson
my_menu: {
  module: fancy_mod
  config: {
    cls: true // validatable as bool
    // ...
    customKeyOne: "stuff", // fancy_mod could check this perhaps, otherwise we just let it through as an "additional property"
  }
}

[cognitivegears]

That looks great! Sounds like a good approach to me.

[NuSkooler]

I suppose another approach for config.hjson at least, would be to just ban anything other than enigma core configuration. Mods could get their own easy to use API for .hjson, or they can use whatever else configuration format/etc. they want.

[cognitivegears]

Yeah I really like that approach for the main config. This sounds super interesting hope we can do this soon