Reference Manual

Lookup tables for configuration file authoring:

Glossary

Term Meaning

Term	Meaning
Definition	The configuration schema model: which properties exist, their types, ranges and documentation. Delivered as a `.def.json5` file by the author of the software you configure.
Configuration	Your data, in a `.cfg.json5` file, bound to one definition by `$definition`.
Workspace	The directory tree `cfu` scans for definition and configuration files.
Workspace root	The top of that tree, marked by a `.confu` with `workspaceRoot: true` or by a repository marker such as `.git`.
CfgSpace	A configuration space (project) inside the workspace, rooted at a folder whose `.confu` sets `cfgSpace: true`. Files merge and reference each other only within one CfgSpace.
Element	Anything a definition declares: an entity, a struct or a parameter.
Entity	An object with identity (`name` or `id`). Only entities can be referenced and merged across files.
Struct	An object without identity, a group of values under its parent.
Parameter	A single value: a number, a string, a boolean, an enum literal, a linker symbol or a reference.
Property name	The key you write, called a relation in the definition manual.
Type path	A type’s full name, the definition name and the type names joined with `::`, for example `SensorEcu::AnalogInput`. It is what `$type` takes.
Multiplicity	How often an element may appear, written `min..max` in the definition. An upper bound above one makes the property a list.
Reference	A parameter whose value is a path to another entity, for example `/SensorEcu/FrontBodyEcu/OilTemp`.
Merged model	The single configuration that results from merging all files of one CfgSpace. It is what the consuming software sees, and what `cfu cfg export-merged` writes.
Merge conflict	Two equally ranked files setting the same value differently.
File type	The priority of a file, written as `$fileType`, which decides who wins a disagreement.
Fragment	A file holding the content of one nested entity, anchored with `$path` and `$type`.
Mixin	A block of content declared once under `$mixins` and applied to the elements its selector picks out.
Annotation	Typed metadata on an element, written with a leading underscore, declared by the definition.
Default and preconfiguration file	`.default.def.json5` and `.preconfig.def.json5` files shipped by the definition author, holding values that merge into your configuration.
Origin	The record of which file and line a merged value came from, added by `cfu cfg export-merged --with-origin`.

Definition

The configuration schema model: which properties exist, their types, ranges and documentation. Delivered as a .def.json5 file by the author of the software you configure.

Configuration

Your data, in a .cfg.json5 file, bound to one definition by $definition.

Workspace

The directory tree cfu scans for definition and configuration files.

Workspace root

The top of that tree, marked by a .confu with workspaceRoot: true or by a repository marker such as .git.

CfgSpace

A configuration space (project) inside the workspace, rooted at a folder whose .confu sets cfgSpace: true. Files merge and reference each other only within one CfgSpace.

Element

Anything a definition declares: an entity, a struct or a parameter.

Entity

An object with identity (name or id). Only entities can be referenced and merged across files.

Struct

An object without identity, a group of values under its parent.

Parameter

A single value: a number, a string, a boolean, an enum literal, a linker symbol or a reference.

Property name

The key you write, called a relation in the definition manual.

Type path

A type’s full name, the definition name and the type names joined with ::, for example SensorEcu::AnalogInput. It is what $type takes.

Multiplicity

How often an element may appear, written min..max in the definition. An upper bound above one makes the property a list.

Reference

A parameter whose value is a path to another entity, for example /SensorEcu/FrontBodyEcu/OilTemp.

Merged model

The single configuration that results from merging all files of one CfgSpace. It is what the consuming software sees, and what cfu cfg export-merged writes.

Merge conflict

Two equally ranked files setting the same value differently.

File type

The priority of a file, written as $fileType, which decides who wins a disagreement.

Fragment

A file holding the content of one nested entity, anchored with $path and $type.

Mixin

A block of content declared once under $mixins and applied to the elements its selector picks out.

Annotation

Typed metadata on an element, written with a leading underscore, declared by the definition.

Default and preconfiguration file

.default.def.json5 and .preconfig.def.json5 files shipped by the definition author, holding values that merge into your configuration.

Origin

The record of which file and line a merged value came from, added by cfu cfg export-merged --with-origin.

File Structure

A complete file from the Nm example, showing the document level keys above the configured root property:

{
    $definition: "Nm@1.0",
    $fileType: "UserConfigPriorityHigh",
    nmNodes: [
        {
            name: "Gateway",
            timeoutTime: 1500
        }
    ]
}

Document Level Keys

Key Meaning

Key	Meaning
`$definition`	Name of the definition this file follows (`definitionName`, not a file path), followed by `@` and the `definitionVersion` the file was written against. Required, and so is the version. A new major version or an older definition is an error.
`$definitionVersion`	The long form of the version, as a separate key instead of `@` in `$definition`. Still supported, but give the version one way only: both at once is an error.
`$fileType`	File priority for merging, see the ladder below. Default: `UserConfig`.
`$path`	Absolute path of the anchor entity of a fragment file, e.g. `/Def/Root/Main/SubSub`. Requires `$type`; only in the two mergeable modes.
`$type`	Type path of the anchor entity of a fragment file, its own type or one it inherits from. Requires `$path`; only in the two mergeable modes.
`$mixins`	List of mixin declarations, see Reusing Content with Mixins. Each entry needs a `$type`, may carry a `$mixin` name and `$applyMixins`, and holds the content to apply. Only in the two mergeable modes.

$definition

Name of the definition this file follows (definitionName, not a file path), followed by @ and the definitionVersion the file was written against. Required, and so is the version. A new major version or an older definition is an error.

$definitionVersion

The long form of the version, as a separate key instead of @ in $definition. Still supported, but give the version one way only: both at once is an error.

$fileType

File priority for merging, see the ladder below. Default: UserConfig.

$path

Absolute path of the anchor entity of a fragment file, e.g. /Def/Root/Main/SubSub. Requires $type; only in the two mergeable modes.

$type

Type path of the anchor entity of a fragment file, its own type or one it inherits from. Requires $path; only in the two mergeable modes.

$mixins

List of mixin declarations, see Reusing Content with Mixins. Each entry needs a $type, may carry a $mixin name and $applyMixins, and holds the content to apply. Only in the two mergeable modes.

Inside one $mixins entry:

Key Meaning

Key	Meaning
`$type`	Type path of the content, and the selector: the mixin reaches every element of that type or of a type inheriting from it. Required.
`$mixin`	Name of the mixin, which narrows it to the elements applying that name. Leaving it out reaches every element of `$type`. An identifier, unique per definition.
`$applyMixins`	Mixins this mixin builds on, see below. It loses against what this entry sets itself. Only on the entry itself, not on the content below it.

$type

Type path of the content, and the selector: the mixin reaches every element of that type or of a type inheriting from it. Required.

$mixin

Name of the mixin, which narrows it to the elements applying that name. Leaving it out reaches every element of $type. An identifier, unique per definition.

$applyMixins

Mixins this mixin builds on, see below. It loses against what this entry sets itself. Only on the entry itself, not on the content below it.

Element Level Keys

On entities:

Key Meaning

Key	Meaning
`name`	Identity among the entity’s siblings. Pattern `^[A-Za-z][A-Za-z0-9_]*$`.
`id`	Globally unique identity; also serves as the name. Same pattern. An entity takes `name` or `id`, never both.
`$type`	Union discriminator, full type path `DefinitionName::TypeName`. Only where the definition declares a union of entity types.
`$applyMixins`	Name of a mixin to apply, or a list of them, see Reusing Content with Mixins. Only in the two mergeable modes.
`$remove`	`true` takes the entity and everything below it out of the merged model, see configuration:multiple-files.adoc#_removing_an_entity. Only in `MultipleFilesEntitiesMergeableWithPriority` and a user-editable `$fileType`, never on the document root or in a `$mixins` body, overriding the files of lower priority only and carrying the target’s identity and nothing else.
`$description`, `$comment`	Free text carried in the model, see below.

name

Identity among the entity’s siblings. Pattern ^[A-Za-z][A-Za-z0-9_]*$.

id

Globally unique identity; also serves as the name. Same pattern. An entity takes name or id, never both.

$type

Union discriminator, full type path DefinitionName::TypeName. Only where the definition declares a union of entity types.

$applyMixins

Name of a mixin to apply, or a list of them, see Reusing Content with Mixins. Only in the two mergeable modes.

$remove

true takes the entity and everything below it out of the merged model, see configuration:multiple-files.adoc#_removing_an_entity. Only in MultipleFilesEntitiesMergeableWithPriority and a user-editable $fileType, never on the document root or in a $mixins body, overriding the files of lower priority only and carrying the target’s identity and nothing else.

$description, $comment

Free text carried in the model, see below.

On structs:

Key Meaning

Key	Meaning
`$type`	Union discriminator, full type path `DefinitionName::TypeName`. Only where the definition declares a union of struct types.
`$applyMixins`	Name of a mixin to apply, or a list of them, see Reusing Content with Mixins. Only in the two mergeable modes.
`$description`, `$comment`	Free text carried in the model, see below.

$type

Union discriminator, full type path DefinitionName::TypeName. Only where the definition declares a union of struct types.

$applyMixins

Name of a mixin to apply, or a list of them, see Reusing Content with Mixins. Only in the two mergeable modes.

$description, $comment

Free text carried in the model, see below.

On parameters in object form:

Key Meaning

Key	Meaning
`value`	The parameter value. Integer parameters also accept hex (`"0x4000_1000"`) and decimal (`"1_000"`) strings grouped by underscores, integer and float parameters unit strings (`"2 MHz"`) and an exponent (`"1e3"`).
`refTarget`	The target path, for reference parameters instead of `value`.
`$description`, `$comment`	Free text carried in the model, see below.

value

The parameter value. Integer parameters also accept hex ("0x4000_1000") and decimal ("1_000") strings grouped by underscores, integer and float parameters unit strings ("2 MHz") and an exponent ("1e3").

refTarget

The target path, for reference parameters instead of value.

$description, $comment

Free text carried in the model, see below.

Everywhere:

Key Meaning

Key	Meaning
`$description`	Documentation of this element instance.
`$comment`	Explanation of a decision, for example why a value deviates.
`_lowerCaseAnnotationName`	A typed annotation; type and allowed placement come from the definition’s `annotationTypes`. Bare value allowed when the annotation has exactly one required field.

$description

Documentation of this element instance.

$comment

Explanation of a decision, for example why a value deviates.

_lowerCaseAnnotationName

A typed annotation; type and allowed placement come from the definition’s annotationTypes. Bare value allowed when the annotation has exactly one required field.

Value Syntax by Definition Type

Definition type You write Example

Definition type	You write	Example
`bool`	`true` / `false`	`selfTest: true`
`u8` … `i64`	Integer values in decimal or hex, or with a unit	`sampleTime: 50`, `adcBaseAddress: "0x4000_1000"`, `sampleTime: "1 s"`
`f64`	Float, as a number or a string, optionally with a unit	`sensorSupplyVoltage: 5.1`, `cutoff: "10 Hz"`
`string`	String, subject to pattern, length, or literals	`shortName: "FBE_01"`
`enum`	One literal as a string	`comfortMode: "ThreeFlashes"`
`linkerSymbol`	Symbol name as a string	`errorHook: "SensFail_ReportDtc"`
`filePath`	Path to a file or folder as a string, checked on disk	`linkerScript: "linker/app.ld"`
`struct`	Aggregation of its fields	`calibration: { offset: -40.0, factor: 0.125 }`
`entity`	Object, optionally with `name` or `id`	`{ name: "OilTemp", … }`
`union` of object types	Object with `$type`	`{ $type: "SensorEcu::AnalogInput", … }`
`union` of primitive types	Bare value, no `$type`	`255` or `"text"`
`ref`	Path string of entity identities	`"/SensorEcu/FrontBodyEcu/OilTemp"`
list (multiplicity max > 1)	Array; brackets omittable only for a single parameter value	`sensors: [ … ]`

bool

true / false

selfTest: true

u8 … i64

Integer values in decimal or hex, or with a unit

sampleTime: 50, adcBaseAddress: "0x4000_1000", sampleTime: "1 s"

f64

Float, as a number or a string, optionally with a unit

sensorSupplyVoltage: 5.1, cutoff: "10 Hz"

string

String, subject to pattern, length, or literals

shortName: "FBE_01"

enum

One literal as a string

comfortMode: "ThreeFlashes"

linkerSymbol

Symbol name as a string

errorHook: "SensFail_ReportDtc"

filePath

Path to a file or folder as a string, checked on disk

linkerScript: "linker/app.ld"

struct

Aggregation of its fields

calibration: { offset: -40.0, factor: 0.125 }

entity

Object, optionally with name or id

{ name: "OilTemp", … }

union of object types

Object with $type

{ $type: "SensorEcu::AnalogInput", … }

union of primitive types

Bare value, no $type

255 or "text"

ref

Path string of entity identities

"/SensorEcu/FrontBodyEcu/OilTemp"

list (multiplicity max > 1)

Array; brackets omittable only for a single parameter value

sensors: [ … ]

Any parameter also accepts the object form { value: …, $description: …, $comment: …, _annotationName: … }.

`$fileType` Priority Ladder

From lowest to highest priority. Equal priorities conflict on differing values; a higher priority wins silently.

Priority $fileType Allowed file suffix

Priority	`$fileType`	Allowed file suffix
1	`DefaultValues`	`.default.def.json5`
2	`DefaultValuesProject`	`.default.def.json5`
3	`GeneratedBelowUserConfig`	`.cfg.json5`
4	`UserConfigPriorityLow`	`.cfg.json5`
5	`UserConfig` (default)	`.cfg.json5`
6	`UserConfigPriorityHigh`	`.cfg.json5`
7	`GeneratedAboveUserConfig`	`.cfg.json5`
8	`PreConfigurationProject`	`.preconfig.def.json5`
9	`PreConfiguration`	`.preconfig.def.json5`
10	`UserOverride`	`.cfg.json5`
11	`PreConfigurationNoOverride`	`.preconfig.def.json5`

DefaultValues

.default.def.json5

DefaultValuesProject

.default.def.json5

GeneratedBelowUserConfig

.cfg.json5

UserConfigPriorityLow

.cfg.json5

UserConfig (default)

.cfg.json5

UserConfigPriorityHigh

.cfg.json5

GeneratedAboveUserConfig

.cfg.json5

PreConfigurationProject

.preconfig.def.json5

PreConfiguration

.preconfig.def.json5

UserOverride

.cfg.json5

PreConfigurationNoOverride

.preconfig.def.json5

The legacy .json variants of each suffix are accepted as well.

`.confu` Settings

Key Meaning

Key	Meaning
`workspaceRoot`	This folder is the workspace root; upward traversal stops here. Default `false`.
`cfgSpace`	This folder roots a CfgSpace, a separate configuration namespace. Default `false`.
`definitions`	List of definition files or directories to load, relative to the `.confu` file. `${env:NAME}` and `${env:NAME:default}` substitution is available. An unset variable without a default is an error, as is a variable value containing the OS path list separator.
`ignoreTraversal`	Load the listed `definitions`, then stop; configuration files in this folder are not discovered.
`executableSettings`	Settings of the `cfu` installation itself, read from the `.confu` in the folder of the executable only. Its single key `autoUpdate` (default `true`) disables the background update check when set to `false`, see Automatic Updates.

workspaceRoot

This folder is the workspace root; upward traversal stops here. Default false.

cfgSpace

This folder roots a CfgSpace, a separate configuration namespace. Default false.

definitions

List of definition files or directories to load, relative to the .confu file. ${env:NAME} and ${env:NAME:default} substitution is available. An unset variable without a default is an error, as is a variable value containing the OS path list separator.

ignoreTraversal

Load the listed definitions, then stop; configuration files in this folder are not discovered.

executableSettings

Settings of the cfu installation itself, read from the .confu in the folder of the executable only. Its single key autoUpdate (default true) disables the background update check when set to false, see Automatic Updates.

cfgSpace cannot be combined with workspaceRoot or ignoreTraversal. Combining workspaceRoot: true with ignoreTraversal: true is valid: the folder stays invisible to enclosing workspaces, but is scanned as its own workspace when passed directly as the input path. Unknown keys are rejected.

CLI Reference

The full command documentation is in the cfu CLI Reference.

Reference Manual

Glossary

File Structure

Document Level Keys

Element Level Keys

Value Syntax by Definition Type

$fileType Priority Ladder

.confu Settings

CLI Reference

`$fileType` Priority Ladder

`.confu` Settings