Reference Manual

Lookup tables for everything a definition file can contain. For prose and examples see the preceding chapters; this page is for checking a key name, a pattern, or a rule quickly. The authoritative machine readable form 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.

Configuration Side Keywords

For completeness, the special keys a definition author must know when reading configuration files:

Key Meaning

$definition

Definition name the file binds to, followed by @ and the definition version it was written against. Both required. An incompatible definitionVersion is an error.

$definitionVersion

The long form of the version, as a separate key. Still supported, but giving the version both ways at once is an error.

$fileType

Priority file type, only in the priority merge mode. Defaults to UserConfig.

$type

Union discriminator, a type path. On a fragment root and in a $mixins entry it names the anchor type instead, see below.

$path

Absolute entity path of a fragment’s anchor, with $type and only in the mergeable modes.

$mixins

Top level list of mixin declarations, only in the mergeable modes. Each entry takes a $type, an optional $mixin name, and the content to apply.

$applyMixins

One mixin name or a list of them, on an entity, a struct, or a $mixins entry.

name, id

Entity identity.

$description, $comment

Documentation and ignored note, on any entity or as reference object members. $description supports Markdown and multiline text is indent-normalized like a definition description.

refTarget

Reference target inside the object form of a reference value.

File Modes and Priorities

See Multi-file configurations for semantics. Priority order of $fileType, lowest first:

DefaultValues, DefaultValuesProject, GeneratedBelowUserConfig, UserConfigPriorityLow, UserConfig, UserConfigPriorityHigh, GeneratedAboveUserConfig, PreConfigurationProject, PreConfiguration, UserOverride, PreConfigurationNoOverride.

File suffix constraints: DefaultValues* types require .default.def.json5, PreConfiguration* types require .preconfig.def.json5, all other types use .cfg.json5/.cfg.json.

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.

.confu Keys

Key Default Meaning

workspaceRoot

false

Marks the folder as workspace root.

cfgSpace

false

Folder forms its own CfgSpace. Exclusive with workspaceRoot and ignoreTraversal.

ignoreTraversal

false

Discovery does not descend below this folder. May be combined with workspaceRoot: the folder is hidden from enclosing workspaces but scanned as its own workspace when passed directly as the input path.

definitions

none

Relative paths of additional definition folders or files to load.

formatter

true

Enables formatter support for the folder.

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.