Configuration Schema Validation

configuration-schema-validation

Summary

Validate that a TOML-formatted options file for LipoCLEAN contains all required configuration fields with correct syntax and structure before passing it to the tool for lipid identification filtering. This skill ensures the configuration is version-specific (MS-DIAL 4 or 5) and ready for execution.

When to use

When you have generated or edited a LipoCLEAN options.txt file using --print MSD4 or --print MSD5 and need to verify it is well-formed before running the analysis. Use this skill as a pre-flight check before invoking --options options.txt to avoid runtime failures caused by malformed or incomplete configuration.

When NOT to use

• The options file has not yet been generated or does not exist on disk — first generate it using --print MSD4/MSD5.
• You are validating raw MS-DIAL export files (.txt m/z matrices) rather than LipoCLEAN configuration — use MS-DIAL export validation instead.
• The input is a training dataset with a label column — this requires data schema validation, not configuration validation.

Inputs

• TOML-formatted options.txt file (generated by --print MSD4 or --print MSD5, or user-edited)
• Target MS-DIAL version identifier (MSD4 or MSD5)

Outputs

• Validation report indicating TOML syntax correctness
• List of required configuration fields present/absent
• Confirmation of version-specific field compatibility
• File path resolution status for MS-DIAL export locations

How to apply

First, generate a version-specific default TOML options file by running LipoCLEAN.exe --print MSD4 (or --print MSD5 for MS-DIAL 5). Then parse and validate the resulting options.txt file by checking: (1) TOML syntax compliance (valid key-value pairs, section headers, data types); (2) presence of all required configuration fields, especially the MS-DIAL export file location paths; (3) consistency with the target MS-DIAL version (do not mix MSD4 and MSD5 fields or models). If validating a user-edited file, confirm the edits preserve TOML structure and that file paths to MS-DIAL exports are absolute or correctly relative. Use the schema implied by the generated default file as the validation template.

Related tools

• LipoCLEAN (Command-line tool that accepts TOML options file; generates default template via --print flag; validates configuration at runtime) — https://github.com/stavis1/LipoCLEAN
• MS-DIAL 4 (Source metabolomics software whose export file paths and column structure are specified in MSD4-version options file)
• MS-DIAL 5 (Newer version of MS-DIAL with renamed and rescaled columns; requires MSD5-specific options file and model)

Examples

LipoCLEAN.exe --print MSD4 > options.txt && python -c "import toml; opts=toml.load('options.txt'); print('Valid TOML' if opts else 'Invalid')"

Evaluation signals

• TOML syntax is valid: file parses without syntax errors when loaded by a TOML parser
• All required configuration keys are present in the options file (e.g., file paths, filtering parameters)
• File paths to MS-DIAL export files resolve to existing .txt or .msp files with expected structure
• Version-specific marker (MSD4 or MSD5) in configuration matches the intended MS-DIAL version and does not mix model/schema versions
• When the validated options.txt is passed to LipoCLEAN via --options, the tool executes without configuration-related errors and produces output and log files

Limitations

• Validation cannot check that MS-DIAL export files themselves are correctly formatted or contain valid lipid identifications — only that paths are specified and resolvable.
• Models trained on MS-DIAL 4 data will not work with MS-DIAL 5 data and vice versa due to column renaming and scaling changes; configuration validation does not verify model–data version compatibility until runtime.
• TOML syntax validation does not verify the semantic correctness of parameter values (e.g., whether filtering thresholds are within reasonable ranges); users must understand what each parameter controls.
• Users must manually ensure blank filtering is NOT selected in MS-DIAL export settings; the options file validation cannot access the MS-DIAL export dialog to confirm this.

Evidence

• [readme] All options, including the location of MS-DIAL export files to analyze, are given to the tool in a TOML formatted text file.: "All options, including the location of MS-DIAL export files to analyze, are given to the tool in a TOML formatted text file."
• [readme] Default options files for MS-DIAL 4 and 5 can be obtained using the --print MSD4 or --print MSD5 command line arguments, respectively. These will create an options.txt file that you can edit.: "Default options files for MS-DIAL 4 and 5 can be obtained using the --print MSD4 or --print MSD5 command line arguments, respectively. These will create an options.txt file that you can edit."
• [other] Confirm that all required configuration fields for MS-DIAL export file locations and filtering parameters are present in the generated file.: "Confirm that all required configuration fields for MS-DIAL export file locations and filtering parameters are present in the generated file."
• [readme] Some columns were renamed and scaled differently between the two versions so a model trained on one version's data will not work with the other. Both the options file and the model are specific to a version of MS-DIAL.: "Some columns were renamed and scaled differently between the two versions so a model trained on one version's data will not work with the other. Both the options file and the model are specific to a"