How Configuration Files Work

This chapter explains what happens between saving a .cfg.json5 file and seeing a diagnostic: the file types involved, how the file binds to its definition, and the validation flow. Workspace & Projects covers how Confµgami finds your files and how .confu files and CfgSpaces structure a workspace.

File Types

Confµgami uses four categories of files:

Extension Type Role

.def.json5 / .def.json

Definition file

Describes the configuration schema model. Authored by Vector developers or contributing customers.

.cfg.json5 / .cfg.json

Configuration file

Holds the actual configuration data. Authored by end-users configuring a product.

.confu

Workspace settings file

Confµgami JSON5 settings. Described in Workspace & Projects.

.def.schema.json / .merged.schema.json

Generated JSON Schema

Build artifact derived from definition files. Not edited by hand.

The .json variants are validated as strict JSON, where comments and any other JSON5 syntax are errors. File suffixes are the source of truth; the directory a file sits in carries no meaning.

Binding to a Definition

Every configuration file starts with a $definition key naming the definition it follows and the version it was written against:

{
    $definition: "TurnIndicator@1.0",
    indicator: {
        name: "FrontLeft",
        flashFrequency: 2,
        comfortMode: "THREE_FLASHES",
        // dimmingLevel is omitted: the default 100 from the definition applies
    }
}

The name is the definitionName from inside the definition file, not the definition’s file name. Resolution happens by name within the workspace, so the definition file can live anywhere Confµgami discovers it.

The version after the @ is required: it records which definitionVersion the configuration was written against, and omitting it is an error. It stays valid for later definition versions of the same major (0.x: the same minor), a new major is an error instead of silently validating against changed rules. The version may also be given as a separate $definitionVersion key, the long form this shorthand replaces. Giving it both ways at once is an error.

The Validation Flow

When you save a file (IDE) or run cfu cfg validate (CLI), Confµgami:

  1. Discovers the workspace files and parses the definitions.

  2. Parses each configuration file and resolves it against its definition: unknown properties, missing required elements, value ranges, patterns, enum literals, and reference targets.

  3. If the definition allows merging across files, merges the entities of each CfgSpace and re-checks multiplicities on the merged result. This step only runs when the individual files are free of errors.

Diagnostics always carry a file, line, and column. Warnings do not stop the merge; errors in any file of a CfgSpace do.

Additional Resources