Naming Conventions

This reference describes the naming rules that Confµgami enforces on property names and enum literals in definition files and the conventions for file names.

Property Names in Definition Files

Property names must match the pattern ^([a-z][A-Za-z0-9]*)$ (lowerCamelCase).

Rules:

  • Start with a lowercase letter.

  • Use only letters and digits after the first character.

  • Do not start or end with verb prefixes such as enabled or disabled.

  • A list entity or struct (max > 1) requires a plural name, a list parameter may use either form.

  • A single-element property requires a singular name. Set allowPropertyNameDeviation: true on the element to override this check.

  • A list entity or struct, or a list with a plural name, must also declare an explicit typeName (the singular of its plural name).

The complete pattern table, including type names, enum literals, and the configuration side identities, is in the Reference Manual under Naming rules.

Enum Literals

Enum literals must match ^[A-Z](_[A-Z0-9]+)$ (SCREAMING_SNAKE_CASE): OFF, THREE_FLASHES, MODE_2. A literal off the convention is an error. Set allowLiteralNameDeviation: true in the enum block when the literals are spelled by an external format.

File Names

File suffixes are the source of truth for the file type; the directory a file sits in carries no meaning.

  • Definition files follow the pattern <name>.def.json5. The base name is free: configuration files bind via $definition to the definitionName inside the file, not to the file name. Keeping the base name equal to the definitionName is recommended for findability.

  • Configuration files follow the pattern <name>.cfg.json5. The base name is chosen by the product or user and carries no special meaning to Confµgami.