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 |
Configuration |
Your data, in a |
Workspace |
The directory tree |
Workspace root |
The top of that tree, marked by a |
CfgSpace |
A configuration space (project) inside the workspace, rooted at a folder whose |
Element |
Anything a definition declares: an entity, a struct or a parameter. |
Entity |
An object with identity ( |
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 |
Multiplicity |
How often an element may appear, written |
Reference |
A parameter whose value is a path to another entity, for example |
Merged model |
The single configuration that results from merging all files of one CfgSpace.
It is what the consuming software sees, and what |
Merge conflict |
Two equally ranked files setting the same value differently. |
File type |
The priority of a file, written as |
Fragment |
A file holding the content of one nested entity, anchored with |
Mixin |
A block of content declared once under |
Annotation |
Typed metadata on an element, written with a leading underscore, declared by the definition. |
Default and preconfiguration file |
|
Origin |
The record of which file and line a merged value came from, added by |
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 |
|---|---|
|
Name of the definition this file follows ( |
|
The long form of the version, as a separate key instead of |
|
File priority for merging, see the ladder below.
Only in |
|
Absolute path of the anchor entity of a fragment file, e.g. |
|
Type path of the anchor entity of a fragment file, its own type or one it inherits from.
Requires |
|
List of mixin declarations, see Reusing Content with Mixins.
Each entry needs a |
Inside one $mixins entry:
| Key | Meaning |
|---|---|
|
Type path of the content, and the selector: the mixin reaches every element of that type or of a type inheriting from it. Required. |
|
Name of the mixin, which narrows it to the elements applying that name.
Leaving it out reaches every element of |
|
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 |
|---|---|
|
Identity among the entity’s siblings.
Pattern |
|
Globally unique identity; also serves as the name.
Same pattern.
An entity takes |
|
Union discriminator, full type path |
|
Name of a mixin to apply, or a list of them, see Reusing Content with Mixins. Only in the two mergeable modes. |
|
|
|
Free text carried in the model, see below. |
On structs:
| Key | Meaning |
|---|---|
|
Union discriminator, full type path |
|
Name of a mixin to apply, or a list of them, see Reusing Content with Mixins. Only in the two mergeable modes. |
|
Free text carried in the model, see below. |
On parameters in object form:
| Key | Meaning |
|---|---|
|
The parameter value.
Integer parameters also accept hex ( |
|
The target path, for reference parameters instead of |
|
Free text carried in the model, see below. |
Everywhere:
| Key | Meaning |
|---|---|
|
Documentation of this element instance.
Markdown, multiline text is indent-normalized like a definition |
|
Explanation of a decision, for example why a value deviates. |
|
A typed annotation; type and allowed placement come from the definition’s |
Value Syntax by Definition Type
| Definition type | You write | Example |
|---|---|---|
|
|
|
|
Integer values in decimal or hex, or with a unit |
|
|
Float, as a number or a string, optionally with a unit |
|
|
String, subject to pattern, length, or literals |
|
|
One literal as a string |
|
|
Symbol name as a string |
|
|
Path to a file or folder as a string, checked on disk |
|
|
Aggregation of its fields |
|
|
Object, optionally with |
|
|
Object with |
|
|
Bare value, no |
|
|
Path string of entity identities |
|
list (multiplicity max > 1) |
Array; brackets omittable only for a single parameter value |
|
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 |
|
|
2 |
|
|
3 |
|
|
4 |
|
|
5 |
|
|
6 |
|
|
7 |
|
|
8 |
|
|
9 |
|
|
10 |
|
|
11 |
|
|
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 |
|---|---|---|
|
yes |
Version of the definition language, currently |
|
yes |
Name and root type of the definition.
UpperCamelCase.
Configurations bind to it via |
|
yes |
Version of the model, |
|
with |
|
|
recommended |
Documentation of the definition. Description renders Markdown. A missing one is reported as an info diagnostic, since both reach the configuration author. |
|
no |
The root children. Every direct child must be an entity element. |
|
no |
Reusable types.
Each entry needs a |
|
no |
Rules of the definition root, run once over the whole configuration, see Constraints. |
|
no |
Custom annotation type declarations. |
|
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 |
|---|---|
|
Short descriptive name, shown in hover and completion. |
|
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 |
|
Note for readers of the definition file, ignored by tooling. |
|
|
|
Same grammar as |
|
|
|
Explicit type name, UpperCamelCase. Required for a list property. For a single element it defaults to the capitalized property name. |
|
Type path of the parent entity. Entities only. |
|
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 |
|
Derives the globally unique |
|
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 |
|
Suppresses the singular/plural name check. |
|
Rules relating several values, each with |
|
Custom annotation value, see Annotations. |
|
Built-in deprecation annotation, see Deprecating Elements. |
Plus exactly one type keyword:
| Keyword | Options | Notes |
|---|---|---|
|
children as nested relations |
Has |
|
children as nested relations |
No identity. No entities among children. |
|
|
Members are type paths of entities or structs.
Discriminated via |
|
type path string |
Element takes the shape of the referenced type. |
|
|
Reference to an entity of one of the listed type paths. |
|
|
|
|
|
|
|
|
|
|
|
Literal lists are mutually exclusive; literals must match |
|
|
Literals are SCREAMING_SNAKE_CASE identifiers, unique ignoring case (see Naming rules). |
|
|
Values checked as C identifiers. |
|
|
Values resolved and checked on disk, see File Path. |
|
|
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 |
|
Not |
Type name / |
|
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 |
Type path |
|
Segments joined with |
Enum literal |
|
Unique within the enum, ignoring case.
Any other identifier matching |
Entity |
|
|
Reference path (config side) |
|
Path segments are entity identities starting at the definition name. |
Annotation key |
|
Derived from the annotation |
globalSettings
| Key | Meaning |
|---|---|
|
Allowed |
|
Allowed |
|
Reference forms configurations may write. |
|
Severity of a reference to a missing target: |
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;
configurationFileModepresent whendefinitionis;typesentries carrytypeName; annotation types carrytargets. - 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, andrefTargetTypesresolve to existing, visible types of the right kind; no reference or inheritance cycles; unions do not directly contain unions. - Values
-
min ⇐ maxand inside the type range,minLength ⇐ maxLength.defaultwithin range, matching pattern, length, and literals. Regex patterns compile. - Modes
-
globalSettingsandconfigurationFileModenot combined; declared modes and file types consistent withglobalSettings.fileMultiplicityonly on a top-level relation of aMultipleFilesdefinition, its maximum within the one ofmultiplicity, and not without effect.
.confu Settings
| Key | Default | Meaning |
|---|---|---|
|
|
This folder is the workspace root; upward traversal stops here. |
|
|
This folder roots a CfgSpace, a separate configuration namespace. |
|
none |
List of definition files or directories to load, relative to the |
|
|
Load the listed |
|
|
Enables formatter support for the folder. |
|
none |
Settings of the |
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.