Generate `config.schema.json` file for validation inside mod managers

[erri120]

SMAPI mods write config.json files into the mod folder. This is the usual modding process:

flowchart TD
    1[Install mod]
    2[Run game to generate config.json]
    3[Edit config.json]
    4[Run Game]
    5{Valid config?}
    1 --> 2 --> 3 --> 4 --> 5
    5 -- Yes --> Done
    5 -- No --> 3

Loading

To make modding easier and less error-prone, mod managers should be able to validate the config.json file without requiring the user to run the game and check the SMAPI logs:

flowchart TD
    1[Install mod]
    2[Run game to generate config.json]
    3[Edit config.json]
    5{Valid config?}
    1 --> 2 --> 3 --> 5
    5 -- Yes --> Done
    5 -- No --> 3

Loading

Currently, mod managers are only able to validate if the config.json file is valid JSON. For validation of properties, mod managers would need a JSON schema file config.schema.json. Such a file could be generated by SMAPI on startup.

Besides validation, a schema file would also allow mod managers to provide rich config editors without requiring users to open external tools like Notepad++ or VS Code. This makes modding even easier and will massively reduce support questions for broken config files.

[Pathoschild]

Hi! SMAPI could generate a schema, but:

• It would be pretty basic. SMAPI has no info about how the mod might validate fields, so it couldn't provide allowed values for most fields (except cases like enum fields).
• It wouldn't handle cases where a mod has multiple config models (e.g. to handle versioning), but I don't think many mods do that.

That said, my concern is that it'd cause confusion for the majority of players who edit it directly. We'd probably have players trying to edit config.schema.json instead of config.json. So ideally the file should be provided in a way that's hidden from players (e.g. stored in a separate internal folder somewhere).

[erri120]

It would be pretty basic. SMAPI has no info about how the mod might validate fields, so it couldn't provide allowed values for most fields (except cases like enum fields).

Right, any validation done in C# that can't be inferred from the type alone wouldn't appear in the schema. I can imagine that some mods might have range requirements on integer values. However, the user wouldn't know about these requirements from looking at the config.json file alone. Since the JSON file generated by SMAPI, if it doesn't exist, it wouldn't contain any comments explaining the requirements to the user. Those requirements would be in the documentation of the mod.

It wouldn't handle cases where a mod has multiple config models (e.g. to handle versioning), but I don't think many mods do that.

Do you know of any mods that do this? I'm curious how they handle config versioning. My idea was generating a schema when calling ReadConfig and the config.json file doesn't exist yet.

That said, my concern is that it'd cause confusion for the majority of players who edit it directly. We'd probably have players trying to edit config.schema.json instead of config.json. So ideally the file should be provided in a way that's hidden from players (e.g. stored in a separate internal folder somewhere).

Would it be enough to put this feature behind a config value in SMAPI itself that's disabled by default? Something inside SConfig like WriteConfigSchema? The mod manager could generate a smapi-internal/config.user.json to automatically enable this feature. With this approach, normal users won't see a config.schema.json file, while mod managers can automatically enable a feature to generate these files.

[erri120]

SMAPI still uses Newtonsoft.Json instead of System.Text.Json, right? Schemas can apparently be created using the JSchemaGenerator: Generating Schemas.