Reference Manual

Lookup tables for configuration and definition file authoring. The chapters hold the prose and examples, this page is for checking a key name, a pattern, or a rule quickly.

Glossary

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 a definition.

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.

Configuration Files

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

$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. Only in MultipleFilesEntitiesMergeableWithPriority. 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

$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

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

$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

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

$description

Documentation of this element instance. Markdown, multiline text is indent-normalized like a definition description.

$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

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, see Multi-File Configurations and Merging for the semantics. Equal priorities conflict on differing values; a higher priority wins silently.

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

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

Definition Files

The authoritative machine readable form of a definition is the definition meta-schema, written by cfu def generate --schema-output.

Document Structure

Top level keys of a .def.json5 file:

Key Required Meaning

$definitionSpecVersion

yes

Version of the definition language, currently "1.0".

definitionName

yes

Name and root type of the definition. UpperCamelCase. Configurations bind to it via $definition.

definitionVersion

yes

Version of the model, major[.minor[.patch]].

configurationFileMode

with definition

SingleFile, MultipleFiles, MultipleFilesEntitiesMergeable, or MultipleFilesEntitiesMergeableWithPriority. Mutually exclusive with globalSettings.

title, description

recommended

Documentation of the definition. Description renders Markdown. A missing one is reported as an info diagnostic, since both reach the configuration author.

definition

no

The root children. Every direct child must be an entity element.

types

no

Reusable types. Each entry needs a typeName.

constraints

no

Rules of the definition root, run once over the whole configuration, see Constraints.

annotationTypes

no

Custom annotation type declarations.

globalSettings

no

Workspace wide mode and file type policy. At most one definition per workspace may set it.

Element Keys

Common keys available on every element (relation):

Key Meaning

title

Short descriptive name, shown in hover and completion.

description

Long documentation, Markdown. Multiline text is indent-normalized: the common leading indentation and a single leading/trailing blank line are removed, so the text can be indented to match the JSON nesting. JSON5 has no raw multiline strings, so end each line with \n\ (a \n escape followed by a line continuation).

$comment

Note for readers of the definition file, ignored by tooling.

multiplicity

"min..max", * for unlimited upper bound, ? for optional lists. Default 0..1.

fileMultiplicity

Same grammar as multiplicity, bounding how many entities of the relation each configuration file holds. Only on a top-level entity of a MultipleFiles definition, see Working with Multiple Files.

scope

definition (default) or public.

typeName

Explicit type name, UpperCamelCase. Required for a list property. For a single element it defaults to the capitalized property name.

inherits

Type path of the parent entity. Entities only.

nameSource

Derives the entity name from one of its own parameters. Use it when the real identity is a value the author writes anyway, such as a fully qualified name. Names an own or inherited 1..1 string property, on a list multiplicity only. An explicit name or id wins. See Deriving the Identity from a Parameter.

idSource

Derives the globally unique id, and with it the name, from one of its own parameters. Use it when that value is unique across the whole configuration, such as a linker symbol. Same rules as nameSource, and mutually exclusive with it.

embeddedTypeHint

Free text hint about the embedded type, documentation only. Use sparingly, only when the embedded side uses a better-fitting type than the configuration type, for example time_t for a u64. Rejected on an entity and a struct, which are aggregates without an embedded type of their own.

allowPropertyNameDeviation

Suppresses the singular/plural name check.

constraints

Rules relating several values, each with name, assert, message and severity, see Constraints.

_<name>

Custom annotation value, see Annotations.

_deprecated

Built-in deprecation annotation, see Deprecating Elements.

Plus exactly one type keyword:

Keyword Options Notes

entity

children as nested relations

Has name/id identity, referencable, mergeable.

struct

children as nested relations

No identity. No entities among children.

union

typeRefs (min 2), allowTypeAmbiguity

Members are type paths of entities or structs. Discriminated via $type unless ambiguity is allowed. Scalar (parameter) or ref members are only allowed when allowTypeAmbiguity: true.

typeRef

type path string

Element takes the shape of the referenced type.

ref

refTargetTypes (min 1)

Reference to an entity of one of the listed type paths.

bool

default

u8 i8 u16 i16 u32 i32 u64 i64

min, max, default, unit, display

display is decimal or hex. Config values accept decimal or 0x hex strings, both with _ separators, an exponent ("1e3") for a whole value, and unit strings ("2 MHz"). unit is a string or { symbol, basePrefix, prefixFamily }, see Units.

f64

min, max, default, unit, display

display supports decimal only. Config values may also be strings, with or without a unit.

string

minLength, maxLength, pattern, literalsExhaustive, literalsNonExhaustive, default

Literal lists are mutually exclusive; literals must match pattern.

enum

literals (required), default, allowLiteralNameDeviation

Literals are SCREAMING_SNAKE_CASE identifiers, unique ignoring case (see Naming rules).

linkerSymbol

language (required, "C"), minLength, maxLength, default

Values checked as C identifiers.

filePath

pathKinds (required), baseResolutionFolder (required), support, globPattern, resolveFilePathOnExport, default

Values resolved and checked on disk, see File Path.

typeSymbolRef

targets (min 1, definition targets only)

Value is a type path of the definition, restricted to the listed element kinds. Only allowed inside an annotation type declaration.

Naming Rules

Item Pattern Additional rules

Property name

^[a-z][A-Za-z0-9]*$ (lowerCamelCase)

Not id, name, $type, $comment, $description. No enable(d)/disable(d) prefix or suffix. Plural for entity and struct lists, either for parameter lists, singular otherwise (exempt suffixes, either fits: Class, Address, Status, Bytes, Flags; override with allowPropertyNameDeviation).

Type name / definitionName

^[A-Z][A-Za-z0-9]*$ (UpperCamelCase)

Unique type path per workspace definition set. Simple names must not clash for generated code. A list entity or struct, or a plural-named list, must set typeName explicitly; it is not derived from the plural property name.

Type path

^([A-Z]::)[A-Z][A-Za-z0-9]*$

Segments joined with ::, starting at the definition name.

Enum literal

^[A-Z](_[A-Z0-9]+)$ (SCREAMING_SNAKE_CASE)

Unique within the enum, ignoring case. Any other identifier matching ^[A-Za-z][A-Za-z0-9_]*$ is an error, override with allowLiteralNameDeviation on the enum.

Entity name / id (config side)

^[A-Za-z][A-Za-z0-9_]*$

id must be globally unique; id doubles as name if no name is set.

Reference path (config side)

^id:<id>$ or ^(/<name>)+$

Path segments are entity identities starting at the definition name.

Annotation key

^_[a-z][A-Za-z0-9]*$

Derived from the annotation typeName with the first letter lowercased.

globalSettings

Key Meaning

supportedConfigurationFileModes

Allowed configurationFileMode values for all definitions in the workspace. Unique, at least one entry.

supportedConfigurationFileTypes

Allowed $fileType values. Requires MultipleFilesEntitiesMergeableWithPriority among the supported modes and must include UserConfig.

refs.allowedRefTypes

Reference forms configurations may write.

refs.unresolvedTargetSeverity

Severity of a reference to a missing target: Error (default), Warning, or Info.

Annotation Retention

Values for retention in an annotation type declaration: Output (the default) keeps the annotation in the sources and in the outputs generated from them, Source limits it to the definition and configuration files and drops it from the merged JSON output.

Annotation Targets

Values for targets in an annotation type declaration. All covers everything; AllDef/AllCfg cover one side; the specific values select an element kind on the definition (…​Def) or configuration (…​Cfg) side:

Document, Entity, Struct, Parameter, String, LinkerSymbol, FilePath, Integer, Float, Enum, Ref, each with the Def or Cfg suffix, plus AnnotationDef for annotating annotation type declarations and TypeSymbolRefDef for typeSymbolRef elements.

The same values restrict a typeSymbolRef, where only the definition side ones are allowed.

Validation Rule Summary

The checks cfu def validate runs on a definition, grouped:

Structure

Required header keys present and well formed; configurationFileMode present when definition is; types entries carry typeName; annotation types carry targets.

Naming

All patterns from Naming rules; duplicate type paths, duplicate enum literals, duplicate union members, duplicate annotation names.

Types and references

typeRef, inherits, union members, and refTargetTypes resolve to existing, visible types of the right kind; no reference or inheritance cycles; unions do not directly contain unions.

Values

min ⇐ max and inside the type range, minLength ⇐ maxLength. default within range, matching pattern, length, and literals. Regex patterns compile.

Modes

globalSettings and configurationFileMode not combined; declared modes and file types consistent with globalSettings. fileMultiplicity only on a top-level relation of a MultipleFiles definition, its maximum within the one of multiplicity, and not without effect.

.confu Settings

Key Default Meaning

workspaceRoot

false

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

cfgSpace

false

This folder roots a CfgSpace, a separate configuration namespace.

definitions

none

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

false

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

formatter

true

Enables formatter support for the folder.

executableSettings

none

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.